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ABOUT THIS GUIDE 






we-ve designed this 8086 Implementor 'p £ul^ 
to provide the information you need to know 
in order to generate various TurboDOS config- 
urations for 8086-family microcomputers, and 
to write the driver modules for various peri- 
pheral devices. This document describes the 
modular architecture and internal programming 
conventions of TurboDOS, and explains the 
procedures for system generation, serializa- 
tion, and distribution. It also provides 
detailed interface specifications for hard- 
ware-dependent driver modules, and includes 
assembler source listings of sample drivers. 



Assumptions 



In writing this guide, we've assumed that you 
are an OEM, dealer, or sophisticated TurboDOS 
user, knowledgable in 8086-family microcompu- 
ter hardware and assembly-language program- 
ming. We've also assumed you have read both 
the Haeiia Q£i£x. and the 33,86 ZLQgzAmm&ila. 
£1LLQ£, and are therefore familiar with the 
commands, external features, and internal 
functions of 8086 TurboDOS. 



Organization 



This guide starts with a section that de- 
scribes the architecture of TurboDOS. It 
explains the function of each internal module 
of the operating system, and how these 
modules may be combined to create the various 
configurations of TurboDOS. 

The next section explains the system genera- 
tion procedure in detail, and describes each 
TurboDOS parameter which can be modified 
during system generation. 

The third section of this guide explains the 
TurboDOS distribution procedure, including 
licensing, serialization, and support. 
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Organization 
(Continued) 



Related Documents 



The fourth section is devoted to an in-depth 
discussion of internal programming conven- 
tions, aimed at the programmer writing 
drivers or resident processes for TurboDOS. 

The fifth section presents formal interface 
specifications for implementing hardware- 
dependent driver modules. 

This guide concludes with a large appendix 
containing assembler source listings of 
actual driver modules. The sample drivers 
cover a wide range of peripheral devices, and 
provide an excellent starting point for 
programmers involved in driver development. 



In addition to this guide, you might be 
interested in four other related documents: 

. TurboDOS 1A. IL§£XlS Guj.jfe 

. TurboDOS 1A. MM. Prograromej-'-s. Quite. 

. T urboDOS l*A IM. Programmer's Quite 

. TurboDOS 1*4. 2M. ImplementPJ.'.s. Quite. 

You should read the first two volumes before 
start into this document. The Usej-S. Quite 
introduces the external features and facili- 
ties of TurboDOS, and describes each TurboDOS 
command. The 8086 Pro,gjamjB.ejLis Quite ex- 
plains the internal workings of TurboDOS, and 
describes each operating system function in 
detail. 

You'll need the Z80 guides if you are pro- 
gramming or configuring a TurboDOS system 
that uses Z80 microprocessors. 



TurboDOS 1.4 8086 
Implementor's Guide 



TABLE OF CONTENTS 



Copyright 1984 by Software 2000 , Inc. 
All rights reserved. 



ARCHITECTURE 



SYSTEM GENERATION 



DISTRIBUTION 



Module Hierarchy 1-1 

Process Level 1-1 

Kernel Level 1-2 

Driver Level 1-2 

TurboDOS Loader 1-2 

Module Flow Diagram 1-3 

Process Modules 1-4 

Kernel Modules 1-5 

Driver Modules 1-8 

Standard Packages 1-8 

Package Contents Table ....... 1-9 

Supplementary Modules 1-10 

Memory Required ..... 1-11 

Other Languages 1-12 

Introduction 2-1 

TLINK Command 2-2 

Patch Points 2-7 

Network Operation 2-21 

Network Model 2-21 

Network Tables 2-21 

Message Forwarding ......... 2-24 

A Complex Example 2-25 

Sysgen Procedure 2-27 

TurboDOS Licensing . 3-1 

Legal Protection 3-1 

User Obligations 3-2 

Dealer Obligations 3-2 

Distributor Obligations 3-3 

Serialization 3-4 

Technical Support 3-5 

SERIAL Command 3-6 

PACKAGE Command 3-8 

Distribution Procedure 3-10 



TurboDOS 1.4 8086 
Implementor ■ s Guide 



TABLE OF CONTENTS 
(Continued) 



Copyright 1984 by Software 2000, Inc. 
All rights reserved. 



CODING CONVENTIONS 



DRIVER INTERFACE 



APPENDICES 



Undefined External References 4-1 

Memory Allocation 4-2 

List Processing ..... 4-3 

Task Dispatching • • • 4-4 

Interrupt Service ..... 4-6 

Poll Routines 4-7 

Mutual Exclusion 4-8 

Sample Driver Using Interrupts .... 4-9 

Sample Driver Using Polling 4-10 

Inter-Process Messages 4-11 

Console Routines 4-12 

Sign-On Message 4-12 

Resident Process 4-13 

User-Defined Function 4-14 

General Notes 5-1 

Initialization 5-2 

Memory Table 5-2 

Console Driver 5-3 

Printer Driver 5-5 

Disk Driver • . • • 5-6 

Network Driver 5-9 

Comm Driver 5-13 

Clock Driver 5-14 

Bootstrap 5-16 

OTOASM Command A_1 

Sample Driver Source Listings B-l 



TurboDOS 1.4 8086 ARCHITECTURE 

Implementor ■ s Guide 



Copyright 1984 by Software 2000, Inc. 
All rights reserved. 



ARCHITECTURE This section introduces you to the internal 

architecture of the TurboDOS operating sys- 
tem. TurboDOS is highly modular, consisting 
of more than forty separate functional 
modules distributed in relocatable form. 
These modules are "building blocks" that you 
can combine in various ways to produce a 
family of compatible operating systems. This 
section describes the modules in detail, and 
describes how to combine them in various 
configurations. 

Possible TurboDOS configurations include: 

. single-user without spooling 

. single-user with spooling 

. network master 

. simple network slave (no local disks) 

. complex network slave (with local disks) 

Numerous subtle variations are possible in 
each of these categories. 



Module Hierarchy The diagram on page 1-3 illustrates how the 

functional modules of TurboDOS interact. As 
the diagram shows, the architecture of Turbo- 
DOS can be viewed as a three-level hierarchy. 



Process Level The highest level of the hierarchy is the 

process level. TurboDOS can support many 
concurrent processes at this level. There is 
one active process that supports the local 
user who is executing commands and programs 
in the local TPA. There are also processes 
to support users running on other computers 
and making requests of the local computer 
over the network. There are processes to 
handle background printing (de-spooling) on 
local printers. Finally, there is a process 
that periodically causes disk buffers to be 
written out to disk. 
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Kernel Level 



Driver Level 



The intermediate level of the hierarchy is 
the JcejLneJ. level. The kernel supports the 
various C-functions and T-functions, and 
controls the sharing of computer resources 
such as processor time, memory, peripheral 
devices, and disk files. Processes make 
requests of the kernel through the entrypoint 
module OSNTRY, which decodes each C-function 
and T-function by number and invokes the 
appropriate kernel module. 



The lowest level of the hierarchy is the 
driver l&isl, and contains all the device- 
dependent drivers necessary to interface 
TurboDOS to the particular hardware being 
used. Drivers must be provided for all peri- 
pherals, including console, printers, disks, 
communications channels, and network inter- 
face. A driver is also required for the 
real-time clock (or other periodic interrupt 
source) . 

TurboDOS is designed to interface with almost 
any kind of peripheral hardware. It operates 
most efficiently with interrupt-driven, DMA- 
type interfaces, but can also work fine using 
polled and programmed-I/O devices. 



TurboDOS Loader 



The TurboDOS loader OSLOAD.CMD is a program 
containing an abbreviated version of the 
kernel and drivers. Its purpose is to load 
the full TurboDOS operating system from a 
disk file (OSMASTER.SYS) into memory at each 
system cold-start. 
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Process Modules 



nodule. .1 



._JFJin£iiGn 



LCLUSR 

LCLMSG 
LCLTBL 
CMDINT 

AUTLOD 

SGLUSR 

AUTLOG 

BIOS 
SUBMIT 

NETSVC 

NETTBL 

NETFWD 

DSPOOL 
FLUSHR 



Responsible for supporting local 
user's TPA activities. 

Contains all O/S error messages. 

Local user option table. 

Command interpreter, processes 
commands from local user. 

Autoload routine which processes 
COLDSTRT.AUT and WARMSTRT. AUT. 

Flushes disk buffers at each 
console input. Use for single- 
user systems instead of FLUSHR. 

Automatic log-on routine. Used 
when full log-on security is not 
desired. See AUTUSR patch point. 

Direct BIOS Call (C-f en 50) . 

Routine to emulate CP/M proces- 
sing of $$$.SUB files. 

Services network requests from 
other processors on the network. 

Tables to define local network 
topology, used by NETSVC+NETREQ. 

Manages network message forward- 
ing. Requires NETREQ+NETSVC . 

Processes background printing. 

Periodically flushes disk buf- 
fers. Use for network master 
configuration instead of SGLUSR. 
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Kernel Modules 



, Mo jlalfi-J . 



?n _. 



OSNTRY Kernel entrypoint moauxe wnicn 
decodes each C-function and 
T-function by number and invokes 
the appropriate kernel module. 

FILMGR File manager responsible for 

requests involving local files. 

FILSUP File support routines used by 
FILMGR. 

FILCOM Processes common file-oriented 
requests that are never sent 
over the network. 

FILLOK File- and record-level interlock 
routines called by FILMGR. 

FFOMGR FIFO management routines called 
by FILLOK. 

DRVLOK Drive interlock routines. 

BUFMGR Buffer manager called by FILMGR. 
Maintains pool of disk buffers 
used to speed local file access. 

DSKMGR Disk manager responsible for 

physical access to local disks, 
called by BUFMGR. 

DSKTBL Table defining drives A-P as 
local or remote disk drives. 

NONFIL Responsible for functions that 
are not file-oriented. 

CPMSUP Processes C-f unctions 7, 8, 24, 
28, 29, 31, 37 and 107 which are 
rarely used. May be omitted. 
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■Jlaiiule 1. 

MPMSUP 
QUEMGR 

CONMGR 
CONTBL 
DOMGR 
INPLN 

LSTMGR 
LSTTBL 

SPOOLR 



COMMGR 
NETREQ 

MSGFMT 
NETMGR 



_H JJin££i0J3 

Processes C-f unctions 141-143, 
153, 160, 161 (optional). 

Emulates MP/M queues, supports 
C-f unctions 134-140 (optional) . 
Requires MPMSUP. 

Responsible for console I/O. 

Links CONMGR to console driver. 

Responsible for do-files. 

Console input line editor used 
by CMDINT and C-f unction 10. 

Responsible for printer output. 

Table defining printers A-P and 
queues A-P as local or remote. 

Print spooler which diverts 
print output to a spool file 
when spooling is activated. 
Also handles direct printing to 
remote printers. 

Responsible for communications 
channel functions. 

Responsible for issuing network 
request messages for all func- 
tions not processed locally. 

Network message format table 
used by NETREQ. 

Network message routing routine 
used by NETSVC and NETREQ. 



1-6 



TurboDOS 1.4 8086 
Implementor ' s Guide 



ARCHITECTURE 

Kernel Modules 
(Continued) 



Copyright 1984 by Software 2000, Inc. 
All rights reserved. 



Kernel Hodules 
(Continued) 




;.tion_ _ 

Loads programs over the network, 

Real-time clock manager keeps 
system date and time. 



DSPCHR Multi-task dispatcher which con- 
trols sharing of the local pro- 
cessor among multiple processes, 

DSPSGL Null dispatcher used as alterna- 
tive to DSPCHR when only one 
process is required (OSLOAD.CMD 
and single-user w/o spooling) . 

MEMMGR Memory manager responsible for 
dynamic allocation of memory, 
and for supporting TPA alloca- 
tion C-functions (53-58) . 

COMSUB Common subroutines used in all 
configurations. 

SYSNIT System initialization routine 
executed at system cold-start. 

RTCNUL Null real-time clock driver, 
used in configurations where 
there is no periodic interrupt 
source. 

CONREM Remote console driver for net- 
work master to support MASTER 
command. 

PATCH 128 bytes of zeroes, may be in- 
cluded to provide patch area. 
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Driver Modules 



Mndiiifi 1 J^ancjJjML 



I CONDR_ 

I 

I LSTDR_ 

I 

I DSKDIL. 

I 

I CKTDR_ 

I 

I COMDRV 

I 

I RTCDRV 

I 

I MEMTBL 

I 

I 

I HDWNIT 

I 



Console I/O driver. 

Printer output driver (s). 

Disk driver (s) . 

Network circuit driver (s) . 

Communications channel driver. 

Real-time clock driver. 

Table defining the size and 
structure of main memory (RAM) . 

Cold-start initialization for 
all hardware- dependent drivers, 



Standard Packages 



To simplify the system generation process, 
the most commonly-used combinations of Turbo- 
DOS modules are pre-packaged into the follow- 
ing standard configurations: 




STDLOADR 
STDSINGL 
STDSPOOL 
STDMASTR 
STDSLAVE 
STDSLAVX 



cold-start loader 
single-user without spooling 
single-user with spooling 
network master 

simple slave w/o local disks 
complex slave with local disks 



The contents of each standard package is 
detailed in the matrix on the next page. 
Most TurboDOS requirements can be satisfied 
by linking the appropriate standard package 
together with a few additional modules plus 
the requisite driver modules. 
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Optional Modules 



To supplement the standard packages, certain 
optional modules (marked by "+" in the matrix 
above) may have to be added. The following 
table explains where these optional modules 
are required: 



1 Module I 
I 

I CONREM 
I CPMSUP 
I MPMSUP 
I MSGFMT 
I NETFWD 
I NETLOD 
I NETREQ 
I PATCH 
I QUEMGR 
I RTCNUL 
I SUBMIT 



__iJhej:e_EeiiuiX£d . — 



Network masters with no console (instead 
To support C-fcns 7, 8, 24, 28, 29, 31, 
To support C-fcns 134-143, 153, 160 and 
Network masters that make requests over 
To support forwarding of network message 
Network masters that load programs over 
Network masters that make requests over 
Wherever a supplementary patch area is r 
To support MP/M queue emulation (C-fcns 
Wherever no RTC driver is available. 
To emulate CP/M processing of $$$.SUB. 



of CONDIO . 
37 and 107. 
161. 

the network, 
s. 

the network, 
the network, 
equired. 
134-140.) 
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Memory Required 



To estimate the memory required by a particu- 
lar TurboDOS configuration, you need to take 
into account the combined size of all func= 
tional modules, driver modules, disk buffers, 
and other dynamic storage. 

Drivers typically require IK to 4K, and can 
be even larger if the hardware is especially 
complex. Disk buffer space should be as 
large as possible for optimum performance, 
especially in a network master. About 4K of 
disk buffer space is reasonable for a single- 
user system, although less can be used in a 
pinch. Other dynamic storage doesn't usually 
exceed IK in single-user systems, 2K in net- 
work masters. 

The following table gives typical memory 
requirements for standard TurboDOS configura- 
tions: 



I,QAP£ SINGL SPOOL MASTR SLKIE 5LAYJL_ 


O/S 10K 17K 19K 25K 
Drivers 2K 2K 2K 3K 
Buffers 4K 4K 4K 16K 
Dynamic IK IK IK 3K 


13K 22K 

IK 2K 

4K 

2K 2K 



Total 



17K 24K 26K 47K 16K 30K 
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Other Languages To facilitate translation into languages 

other than English, TurboDOS has been 
implemented with all textual messages 
segregated into separate modules. All such 
message modules are available in source form 
to TurboDOS OEM licensees upon request. 

The following modules contain all TurboDOS 
operating system messages: 

IJoiflajZj CsjifciUlis, 

I 

I LCLMSG Most operating system messages. 

I SPLMSG Spooler error messages. 

I LDRMSG Loader messages for OSLOAD.CMD. 



In addition, a separate message module is 
available for each TurboDOS command. 
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SYSTEM GENERATION 



This section explains the TurboDOS system 

rtonai'afi r\vs mir ^\/"ti!s<^ii»r<-v tti /3» ^«a t 1 T ^ Acs e r*ir A V\e\ es 

^CllCLUkXVll ^/l vx^cuutc J.ii vtv^ i~ w. J. J- . J. w U^a^l. J.UWU 

how to use TLINK to link a desired set of 
TurboDOS modules together, and details the 
numerous system patch points which may be 
modified during system generation. Step-by- 
step procedures and examples are provided. 



Introduction 



The functional modules of TurboDOS are dis- 
tributed in relocatable object form (.0 
files). Hardware-dependent driver modules 
are furnished in the same fashion. The 
TurboDOS TLINK command is a specialized 
linker used to bind the desired combination 
of modules together into an executable 
version of TurboDOS. TLINK also includes a 
symbolic patch facility used to modify a 
variety of operating system parameters. 

To generate a complete TurboDOS system, you 
typically must use TLINK several times. At 
minimum, you have to generate both a loader 
0SL0AD.CMD and a master operating system 
OSMASTER.SYS. For a networking system you 
also have to generate a slave operating 
system OSSLAVE.SYS. Complex networks may 
require generation of several different slave 
or master configurations. Finally, you may 
have to use TLINK to generate a cold-start 
bootstrap routine for the start-up PROM or 
boot track. 

At cold-start, the bootstrap routine loads 
the loader program OSLOAD.CMD into the TPA of 
the master computer and executes it. OSLOAD 
loads the master operating system from the 
file OSMASTER.SYS into memory. The master 
operating system then down-loads the slave 
operating system from the file OSSLAVE.SYS 
over the network into each slave computer. 



2-1 



TurboDOS 1.4 8086 
Implementor ' s Guide 



SYSTEM GENERATION 
TLINK Command 



Copyright 1984 by Software 2000, Inc. 
All rights reserved. 



TLINK Command 



Syntax 



Explanation 



The TLINK command is a specialized linker 
used for 8086 TurboDOS system generation, and 
may also be used as a general-purpose linker 
for object modules produced by the TurboDOS 
assembler TASM. 



I TLINK inputfn {outputfn} {-options} 



The TLINK command links a specified collec- 
tion of relocatable object modules together 
into a single executable file. The "inputfn 
argument identifies the two input files used 
by TLINK: a configuration file "inputfn.GEN" 
and a parameter file "inputfn. PAR". The 
"outputfn" argument specifies the name of the 
executable output file to be created (normal- 
ly type .CMD or .SYS). If "outputfn^ is 
omitted from the command, then "inputfn" is 
also used as the name of the executable out- 
put file, and should include an explicit file 
type (.CMD or .SYS). 

If the .GEN file is found, it must contain 
the list of object modules (.0 files) to be 
linked together. If the configuration file 
is not found, then TLINK operates in an 
interactive mode. You are prompted by an 
asterisk * to enter a series of directives 
from the console. The syntax of each direc- 
tive (or each line of the .GEN file) is: 



I objfile {,objf ile). .. {; comment) 



l„ 



The object files are assumed to have type .0 
unless a type is given explicitly. A null 
directive (or the end of the .GEN file) ter- 
minates the prompting sequence and causes 
processing to proceed. 
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(Continued) 



Options 



After obtaining the list of modules from tne 
file or console, TLINK links all of the 
modules together, a two-pass process that 
displays the name of each module as it is 
encountered. When the linking phase is com- 
plete, TLINK looks for a parameter file 
"inputf n.PAR" and processes it if present 
(described below). Finally, the executable 
file (.CMD or .SYS) is written out to disk. 

NOTE: Each module of the TurboDOS operating 
system is magnetically serialized with a 
unique serial number. The serial number 
consists of two components: an "origin 
number" which identifies the issuing TurboDOS 
licensee, and a "unit number" which uniquely 
identifies each copy of TurboDOS issued by 
that licensee. When used for TurboDOS 
operating system generation, TLINK verifies 
that all modules to be linked are serialized 
consistently, and serializes the executable 
file accordingly. 

Options are always preceded by a "-" prefix, 
and may appear before, between, or after the 
file names. Several options may be concate- 
nated after a single "-" prefix. 



Explanation 



-8 
-B 
-C 
-D 
-H 
-L 
-M 
-R 
-S 
-U 
-X 



Force 8080 model (single group) 

No 128-byte base page 

List to console, not to printer 

Force data group G-Max to 64K 

No .CMD header (implies -8, -B) 

Listing only, no output file 

List link map 

List inter-module references 

List sorted symbol table 

List unsorted symbol table 

Diagnose undefined references 
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Parameter File TLINK includes a symbolic patch facility that 

may be used during TurboDOS system generation 
to override various operating system para- 
meters and to effect necessary software cor- 
rections. Patches must be stored in a .PAR 
file. The syntax of each .PAR file entry is: 



I location » value {, value}... {;comment> I 



where the "value" arguments are to be stored 
in consecutive memory locations starting with 
the address specified by "location". 

The "location" argument may be the name of a 
public symbol, an integer constant, or an 
expression composed of names and integer 
constants connected by + or - operators. 
Integer constants must begin with a digit to 
distinguish them from names. Constants of 
the form "Oxdddd" are taken to be hexadeci- 
mal. Constants of the form "Odddddd" are 
taken to be octal. Constants that start with 
a nonzero digit are taken to be decimal. The 
"location" expression must be followed by an 
equal-sign = character. 

The "value" arguments may be expressions (as 
defined above) or quoted ASCII strings, and 
must be separated by commas. A "value" ex- 
pression is stored as a 16-bit word if its 
value exceeds 255 or if it is enclosed in 
parentheses (...) or brackets [...]; other- 
wise, it is stored as an 8-bit byte. An 
expression enclosed in brackets is treated as 
IP-relative (for example, the target address 
of a CALL or JMP instruction). A quoted 
ASCII string must be enclosed by quotes 
"...", and is stored as a sequence of 8-bit 
bytes. Within a quoted string, ASCII control 
characters may be specified by using TASM 
backslant escape sequences. 
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Example 



In the following example, TLINK is used to 
link a single— user TurboDOS system for an IBM 
Personal Computer, using the modules listed 
in OSMASTER.GEN and patches in OSMASTER.PAR, 
creating the executable file OSMASTER.SYS. 



A} TLINK OSMASTER.SYS -M 

Copyright 1984, Software 2000, Inc. 

* ; Single-user without spooling for 

IBM Personal Computer with 256K RAM 



STDSINGL 

CPMSUP 

CONIPC 

LSTACA 

NITIPC 

DSKIPC 

MSTIPC 

RTCIPC 



standard single-user pkg. 
seldom-used CP/M functions 
IBM PC console driver 
IBM PC serial list driver 
IBM PC initialization 
IBM PC floppy disk driver 
IBM PC 256K mem spec table 
IBM PC real-time clock drvr 



Pass 1 

LCLUSR LCLTBL CMDINT AUTLOD SGLUSR etc. 

Pass 2 

LCLDSR LCLTBL CMDINT AUTLOD SGLUSR etc. 



Processing par 
; Patches for 



ameter file: 

single-user w/o spooling 
; dynamic memory area (16K) 
;but limit to first 64K 
logon to user privileg. 
number of disk buffers 
end-of-print character ~Z 
search drive A 
direct printing mode 



Writing output file A: OSMASTER.SYS 
0A> 



OSMLEN 


=5 


1024 


OSMTOP 


as 


0x100 


AUTUSR 


= 


0x80 


NMBUFS 


a= 


8 


EOPCHR 


as 


OxlA 


SRHDRV 


= 


1 


PRTMOD 


as 
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Error Messages 



Serial number violation 
Not enough memory # 
No object files specified 
Can't open object file 
Non-privileged user 
Unexpected EOF in object file 
Bad token in object file: <type> 
Can't create output file 
Can't write output file 
Load address out-of-bounds 
Duplicate transfer address 
Duplicate def: <name> 
Undefined name: <name> 
Too many externals in module 
Name table overflow 
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Patch Points 



The following table describes various public 
^rmKAic in TnrhnnnR whip.h vou mav wish to 
modify using the symbolic patch facility of 
TLINK. (Other patch points may exist in 
hardware-dependent drivers, but they are 
beyond the scope of this document.) 



^jSyjRbfiI_J EfijEfllOt-XallJfi S M0d.u J. f L 

ABTCHR = 0x03 ;CTRL-C CONTBL 

Abort character (after attention) . 



ATNBEL = 0x07 ;CTRL-G CONTBL 

Attention-received warning character. 



ATNCHR = 0x13 ;CTRL-S 



CONTBL 



Attention character. May be patched to 
another character if the default value of 
CTRL-S is needed by application programs. 
A common choice is zero (NUL) , which al- 
lows the console BREAK key to be used as 
an attention key. 



AUTUSR = OxFF 



AUTLOG 



Automatic log-on user number. Default 
value of OxFF requires that user log-on 
via LOGON command. If automatic log-on 
desired at cold-start, patch AUTUSR to 
the desired user number (0-31) , and set 
the sign-bit if a privileged log-on is 
desired. Generally patched to 0x80 in 
single-user systems to cause automatic 
privileged log-on to user zero. 
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Patch Points 
(Continued) 



symbol I JtelauU^XAkie LMoAuliL. 

BFLDLY = (300) FLUSHR 

Buffer flush delay determines how often 
disk buffers are written to disk, stated 
in system "ticks". Default value (300 
decimal) causes buffers to be flushed 
about every five seconds (assuming 60 
ticks per second) . 



BUFBAS = (0000) 



BUFMGR 



Base paragraph address of external disk 
buffer area (see BUFLEN) . 



BUFLEN = (0000) 



BUFMGR 



Length (in paragraphs) of external disk 
buffer area starting at BUFLEN. Default 
value (0000) indicates that buffers are 
to be allocated from the regular dynamic 
memory pool (see OSMLEN, OSMTOP) . 



BUFSIZ = 3 



BUFMGR 



Default disk buffer size (0=128, 1=256, 
2=512, 3=1K,..., 7=16K). Default value 
specifies IK disk buffers. 
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Patch Points 
(Continued) 



Symbol I Defa ult.. Value I HpflBlfl.. I 

CKTAST = (0x0000) f (CKTDRA) , NETTBL 
(0x0100) , (CKTDRB) , 
(0x0200) ,(CKTDRC), 
(0x0300) , (CKTDRD) 

Circuit assignment table defines network 
topology. Contains NMBCKT two-word en- 
tries, one for each network circuit to 
which this processor is attached. The 
first word of each entry specifies the 
network address by which this processor 
is known on a particular circuit, and the 
second word specifies the entrypoint ad- 
dress of the circuit driver responsible 
for that circuit. (Possibly several cir- 
cuits may be handled by the same driver.) 



CLBLEN =157 



CMDINT 



Command line buffer length defines long- 
est permissible command line. The de- 
fault value permits two 80-char lines. 



CLPCHR = n >" 

Command line prompt character. 



CMDINT 



CLSCHR - "\\7 S \T n ^"* CMDINT 

Command line separator character. 



COLDFN = 0, n COLDSTRT n , n AUT n 



AUTLOD 



File name and drive for cold-start auto- 
load processing (in FCB format). 
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Patch Points 
(Continued) 



I Symbol 1 J2fil5iLLLJ?aLU£ 



COMPAT = 



J_JSPj!l2le-~ 
FILCOM 



Default compatibility flags which define 
rules to be used for file-sharing. Patch 
to 0xF8 to relax most MP/M restrictions. 



CONAST a 0,(CONDRA) 



CONTBL 



Console assignment table defines how con- 
sole I/O is handled. First byte passed 
to console driver, and commonly defines 
the channel number (e.g., serial port) to 
be used for the console. Following word 
specifies the entrypoint address of the 
console driver to be used. 



CPMVER = 0x31 



NONFIL 



CP/M BDOS version number returned by 
C-f unction 12 in BL-register. 



DEFDID - (0) 



NETTBL 



Default network destination ID, used for 
routing all network requests that are not 
related to a particular disk drive, queue 
or printer. In a slave, DEFDID should be 
set to the network address of the master. 
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Patch Points 
/« ti_. ji% 

iv*uiicxiiueuj 



I Symbol 1 JBefAUli-^sJUas LitefluJg-. 



DSKAST = 0, (DSKDRA) ,1, (DSKDRB) , 
OxFF, (0) ,0xFF,(0) f ... 



DSKTBL 



Disk assignment table, an array of 16 
three-byte entries (one for each drive 
letter A-P) that defines which drives are 
local, remote, and invalid. 

For a local drive, the first byte must 
not have the sign-bit set. That byte is 
passed to the disk driver, and is common- 
ly used to differentiate between multiple 
drives connected to a single controller. 
The following word specifies the entry- 
point address of the disk driver to be 
used. 

For a remote drive, the first byte must 
have the sign-bit set. The low-order 
bits of that byte specify the drive let- 
ter to be accessed on the remote proces- 
sor. The following word specifies the 
network address of the remote processor. 

For an invalid drive, the first byte must 
be OxFF, and the following word should be 
(0) . 

NOTE: In slave configurations STDSLAVE 
and STDSLAVX, the default values are: 

DSKAST = 0x80, (0) ,0x81,(0) , 
0x82,(0) ,0x83,(0) , 
... ,0x8E, (0) ,0x8F, (0) 



2-11 



TurboDOS 1.4 8086 
Implementor ■ s Guide 



SYSTEM GENERATION 

Patch Points 
(Continued) 



Copyright 1984 by Software 2000, Inc 
All rights reserved. 



Patch Points 
(Continued) 






^mJaoJLJ nelsiLLfc-^filii^ 



DSPPAT = 1,1,1,. . . fl 



._JLlta£iil£_ 

LSTTBL 



De-spool printer assignment table, an ar- 
ray of 16 bytes (one for each printer 
letter A-P) that defines the initial 
queue to which each printer is assigned. 
Values 1 through 16 correspond to queues 
A-P, and means that the printer is off- 
line. The default value assigns all 
printers to queue A. 



ECOCHR = 0x10 ;CTRL-P CONTBL 

Echo-print character (after attention) . 



EOPCHR = 



LSTTBL 



End-of-print character. May be patched 
to any non-null character, in which case 
the presence of that character in the 
print output stream will automatically 
signal an end-of-print- job condition. 
The value zero disables this feature. 



FW^t/l / (o/fFFE^ (Ox^FFrf , NETTBL 
if/ ^OxFF^F) , (^kFE^F) ,g*5f 

Network forwarding table, an array of 
two-byte entries that define any explicit 
message forwarding routes to be used by 
this processor. The first byte of each 
entry specifies a "foreign" circuit num- 
ber N, and the second byte a "domestic" 
circuit number C. Any messages destined 
for circuit N will be routed via circuit 
C. This table is variable-length, termi- 
nated by OxFF, and defaults to empty. 
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Patch Points 

vV/Uiitiiiucu/ 



I.Hh 



Wv 



>\<^ 



A 1} 



Symbol I E£fault_Kaltte I. MP.dpJ.g_, I 

i 

LDCOLD = OxFF AUTLOD 

Cold-start autoload enable flag. Patch 
to zero if you want to disable the cold- 
start autoload feature (COLDSTRT.AUT) . 



LDWARM = OxFF 



AUTLOD 



Warm-start autoload enable flag. Patch 
to zero if you want to disable the warm- 
start autoload feature (WARMSTRT.AUT) . 



LOADFN = 0, "OSMASTER", "SYS 



OSLOAD 



Default file name and drive (in FCB for- 
mat) loaded by OSLOAD.COM. Drive field 
(FCB byte 00 may be patched to an expli- 
cit drive value to inhibit scanning. 



LOGUSR = 31 FILCOM 

User number for logged-off state. 



MAXMBS = 



NETMGR 



Maximum number of message buffers that 
will ever be allocated. Default value of 
means number of message buffers is 
limited only to size of available memory. 



(ChfCCt? -Oyflooo - Oy qoH 6) • oS tTM V*£. 
7ty <?/•■«»•,- Bur*** - 6wf Go s ' 
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I symbol I Default Value 

MAXRPS = 



1 Module. 



NETMGR 



Maximum number of reply packets that will 
ever be allocated. Default value of 
means number of reply packets is limited 
only to the size of available memory. 



NMBCKT = 1 



NETTBL 



Number of network circuits to which this 
processor is connected. 



NMBMBS = 



NETMGR 



Number of message buffers pre-allocated 
at cold-start. Message buffers are allo- 
cated dynamically as needed, but this may 
cause fragmentation which prevents you 
from changing the size of the disk buffer 
pool with the BUFFERS command. If this is 
important, patching NMBMBS to a suitable 
positive value will eliminate the problem 
(twice the number of network nodes is a 
good starting value to try) . 



NMBRPS = 



NETMGR 



Number of reply packets pre-allocated at 
cold-start. Reply packets are allocated 
dynamically as needed, but this may cause 
fragmentation which prevents you from 
changing the size of the disk buffer pool 
with the BUFFERS command. If this is 
important, patching NMBRPS to a suitable 
positive value will eliminate the problem 
(the number of network nodes is a good 
starting value to try) . 
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^ 



symbol I JBef auJi:.. Value LltedHlfi. 



NMBSVC = 2 



NETSVC 



Number of network server processes to be 
activated. (The number of network nodes 
is a good starting value to try.) 



NMBUFS = 4 



BUFMGR 



Default number of disk buffers allocated 
at cold-start. Must be at least 2. For 
optimum performance, allocate as many 
buffers as possible (consistent with TPA 
and other memory requirements) . 



OSMLEN = (128) ;2K bytes 



MEMMGR 



Length (in paragraphs) of the memory area 
to be allocated immediately above the 
TurboDOS operating system resident for 
dynamic working storage. This area must 
accomodate disk buffers if no external 
disk buffer area is defined (BUFLEN is 
zero) . The default value (128 paragraphs 
or 2K bytes) is appropriate for a simple 
slave with no disk buffers. For other 
configurations, patch OSMLEN to a value 
large enough to accomodate dynamic memory 
needs. Divide required length in bytes 
by 16 to give the value of OSMLEN in 
paragraphs. (See OSMTOP.) 
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v« ^ 



\j<*<^ ' 






4"b 



T ' 



Ot.1 



Symbol 1 B£f£lilt Value. 

OSMTOP = (0000) 



__J_Mo^uie_ 
MEMMGR 



Absolute upper bound (paragraph address) 
for dynamic working storage area. The 
actual upper bound is either OSMTOP or 
the top of TurboDOS plus OSMLEN, which- 
ever is smaller. The default value of 
zero indicates no specified upper bound. 



PRTCHR = OxOC ;CTRL-L 



CONTBL 



End-print character (after attention). 
This is a console attention-response, not 
to be confused with EOPCHR. 



PRTMOD = 1 



LCLTBL 



Initial print mode for local user. The 
default value of 1 specifies spooling. 
Patch to for direct, or 2 for console. 
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\ \,MU LXU UCU # 



Symbol, J Jte£££l£-H&l££ 



PTRAST = 0,(LSTDRA) ,0xFF, (0) , 
OxFF, (0) ,0xFF, (0) f ... 



Module, 



LSTTBL 



Printer assignment table, an array of 16 
three-byte entries (one for each printer 
letter A-P) that defines which printers 
are local, remote, and invalid. 

For a local printer, the first byte must 
not have the sign-bit set. That byte is 
passed to the disk pr inter r, and is com- 
monly defines the channel number (e.g., 
serial port) to be used for the printer. 
The following word specifies the entry- 
point address of the printer driver. 

For a remote printer, the first byte must 
have the sign-bit set. The low-order 
bits of that byte specify the printer 
letter to be accessed on the remote pro- 
cessor. The following word specifies the 
network address of the remote processor. 

For an invalid printer, the first byte 
must be OxFF, and the following word 
should be (0) . 

NOTE: In slave configurations STDSLAVE 
and STDSLAVX, the default values are: 

PTRAST = 0x80, (0) ,0x81, (0) , 
0x82,(0) ,0x83,(0) , 
.. . ,0x8E, (0) ,0x8F, (0) 
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SymboJL J Jte£aul£-li&±U£ 1 Modu li - 



QUEAST = 0,(0) ,0xFF, (0) , 

0xFF,(0) r 0xFF, (0) ,... 



LSTTBL 



Queue assignment table, an array of 16 
three-byte entries (one for each queue 
letter A-P) that defines which queues are 
local, remote, and invalid. 

For a local queue, all three bytes must 
be set to zero. 

For a remote queue, the first byte must 
have the sign-bit set. The low-order 
bits of that byte specify the queue let- 
ter to be accessed on the remote proces- 
sor. The following word specifies the 
network address of the remote processor. 

For an invalid queue, the first byte must 
be OxFF, and the following word should be 
(0). 

NOTE: In slave configurations STDSLAVE 
and STDSLAVX, the default values are: 

QUEAST = 0x80, (0) ,0x81, (0) , 
0x82,(0), 0x83,(0) , 
... ,0x8E,(0) ,0x8F,(0) 



QUEDLY = (0000) 



QUEMGR 



Polling delay used in unconditional Read 
Queue (when queue is empty) and Write 
Queue (when queue is full) , stated in 
system "ticks". If RTC driver is avail- 
able, patch to largest delay that yields 
reasonable queue performance. 
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Patch Points 
(Continued) 



L SymhpJL_L- 

i 

QUEDRV = OxFF 



^faialfc_;EaJLii£ Liloj|iLLe_ 

QUEMGR 



Drive used for FIFOs that emulate MP/M 
queues. Default value OxFF means use the 
system disk (disk from which TurboDOS was 
loaded at cold-start) . Patch to - 15 
to specify a particular drive A-P. 



QUEPTR = 1 



LCLTBL 



Initial queue or printer assignment. If 
PRTMOD = 1 (spooling), QUEPTR specifies a 
queue assignment. If PRTMOD = (direct) 
QUEPTR specifies a printer assignment. 
In both cases, values 1 through 16 corre- 
spond to letters A-P, and zero means do 
not queue or print off-line. 



RCNMSK = OxFF 



MPMSUP 



Mask used in deriving a console number 
from a network node in C-f unction 153. 



RCNOFF = 



MPMSUP 



Offset used in deriving a console number 
from a network node in C-f unction 153. 



RESCHR = 0x11 ;CTRL-Q CONTBL 

Resume character (after attention) . 
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Patch Points 
(Continued) 



symbol. J Default value- 1 M od ule- 



SCANDN = 



OSLOAD 



Scan direction flag for OSLOAD. Patch to 
OxFF to scan P-to-A (instead of A-to-P) . 



SLVFN = "OSSLAVE ","SYS 



NETSVC 



Name and type of file (in FCB format) to 
be down-loaded into slave processors. 



SPLDRV = OxFF 



LCLTBL 



Initial spool drive. Default value OxFF 
indicates spool to system disk (disk from 
which TurboDOS was loaded at cold-start) . 
Patch to - 15 to specify drive A-P. 



SRHDRV = 



CMDINT 



Search drive for command files. Patch to 
value 1 through 16 to search drive A-P 
if command is not found on current 
(default) drive. Patch to OxFF to search 
system disk (disk from which TurboDOS was 
loaded at cold-start) . Default value 
disables this feature altogether. 



SUBFN = 0,"$$$ n ,"SUB B SUBMIT 
FCB for emulating CP/M submit files. 



WARMFN = 0,"WARMSTRT", "AUT 1 



AUTLOD 



File name and drive for warm-start auto- 
load processing (in FCB format). 
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Network Operation TurboDOS accomodates a wide variety of net- 
work topologies, ranging from tue simpxes*, 
point-to-point master/slave networks to the 
most complex star, ring, and hierarchical 
structures. 



Network Model 



A TurboDOS network is defined to consist of 
up to 255 circuits , with up to 255 np£e.s 
(processors) on each circuit. Each node has 
a unique 16-bit network address consisting of 
an 8-bit circuit number plus an 8-bit node 
number (on that circuit). 

Any processor may be connected to several 
circuits, if desired. A processor connected 
to multiple circuits has multiple network 
addresses, one for each circuit. Such a 
processor even may be set up to perform mes- 
sage forwarding from one circuit to another, 
permitting dialogue between network nodes 
that do not share a common circuit between 
them (more on this later) . 



Network Tables 



The actual network topology is defined by a 
series of tables in each processor. The 
tables are set up during system generation, 
and define the network as "seen" from the 
viewpoint of each processor. The tables are: 



Symt>x>l__L 



Pjescj i pj:ipii 



NMBCKT A byte value that defines the 
number of network circuits to 
which this processor is connec- 
ted. 
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Network Tables 
(Continued) 



symbol l Description 



CKTAST The circuit assignment table 

containing NMBCKT entries defin- 
ing the network address by which 
this processor is known on each 
circuit, and specifying the net- 
work circuit driver responsible 
for each handling each circuit. 

DSKAST The disk assignment table that 
specifies for all drive letters 
A-P which are local, remote, and 
invalid. This table specifies 
a network address for each re- 
mote drive, and a disk driver 
for each local drive. 

PTRAST The printer assignment table 

that specifies for all printer 
letters A-P which are local, re- 
mote, and invalid. This table 
specifies a network address for 
each remote printer, and a prin- 
ter driver for each local prin- 
ter. 

QUEAST The queue assignment table that 
specifies for all queue letters 
A-P which are local, remote, and 
invalid. This table specifies a 
network address for each remote 
queue. 

DEFDID The default network destination 
ID, used for routing all network 
requests that are not related to 
a specific disk drive, printer, 
or queue. 
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Network Tables 
(Continued) 



1 Pescripiipii, 



FWDTBL The message forwarding table 
that specifies any additional 
circuits (not directly connected 
to this processor) which may be 
accessed via explicit message 
forwarding, and how messages 
destined for such circuits are 
to be routed. 



These tables are pre-defined with default 
values to make set-up of simple master/slave 
networks very easy. For complex multi- 
circuit networks, the set-up is somewhat more 
complicated (as might be expected). 

Refer to the preceding £aicii Poinds sub- 
section for details of the organization and 
defaults for these network tables. 
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Message Forwarding The TurboDOS module NETFWD supports both 

"implicit" and "explicit" forwarding of net- 
work messages. To understand the distinc- 
tion, consider the case of a network with 
three processors (PI, P2, and P3) connected 
by two circuits (CI and C2) as follows: 




A program running in PI makes an access to 
drive D. Suppose the disk assignment tables 
in the three processors are set up in the 
following fashion: 

. Pi's DSKAST defines its drive D as a 
remote reference to P2's drive B. 

. P2 , s DSKAST defines its drive B as a 
remote reference to P3's drive A. 

. P3's DSKAST defines its drive A as a 
local device attached directly to P3. 

In this case, Pi's access to its drive D 
actually winds up implicitly accessing P3's 
drive A. This is im plicit forwarding. 

Alternatively, suppose Pi's DSKAST defines 
its drive D as a remote reference to P3's 
drive A, and that Pi's FWDTBL provides that 
messages destined for circuit C2 may be 
routed via CI. In this case, PI sends a 
request to P3 on circuit CI. P2 receives the 
request, recognizes that it should be forwar- 
ded, and retransmits the request to P3 via 
circuit C2. Thus, PI accesses P3's drive A 
with the assistance of P2, but this time PI 
is not aware of P2's role in the transaction. 
This is ex plicit forwarding. 
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A Complex Example 



Let's take a reasonably complex network situ- 
ation and see how to construct the required 
.GEN and .PAR files. 

Our hardware is a board-and-bus microcomputer 
system consisting of an 80286 CPU running in 
unmapped (8086) mode, 128K of RAM, hard disk 
and floppy disk subsystems (all these make up 
the master processor), and several single- 
board slave computers with 80186 CPUs and 
256K of RAM each. The master processor is 
interfaced to two printers via RS232 serial 
ports: a daisywheel printer on port using 
XON/XOFF protocol and a matrix printer on 
port 1 using clear-to-send handshaking. In 
addition, the master has a high-speed RS422 
interface connecting it to another board-and- 
bus system of similar configuration some 
distance away. 

We want to configure a TurboDOS system for 
this hardware that permits all of the users 
of each system to access the hard disk, 
floppy disks, and printers attached to both 
the local and remote system. We might create 
the following OSMASTER.GEN file: 



; OSMASTER, 

STDMASTR 

NETREQ 

MSGFMT 

CONREM 

LSTXON 

Lo XL. J.O 

DSKHDC 
DSKFDC 
CKTSLV 
CKT422 
RTCDRV 
NITDRV 
MEMTBL 



GEN for complex example 
standard master package 
to make requests of other sys 
needed by NETREQ 
no console on the master 
XON/XOFF for daisy (LSTDRA) 
CTS for matrix (LSTDRB) 
hard disk controller (DSKDRA) 
floppy disk control. (DSKDRB) 
circuit driver for slaves (CO) 
circuit driver for RS422 (CI) 
real-time clock driver 
hardware initialization driver 
memory specification table 
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A Complex Example 
(Continued) 



Our system generation task is completed by 
creating the companion OSMASTER.PAR file: 



; OSMASTER.PAR for complex example 
NMBCKT =2 ; 2 network circuits: 
CKTAST - (0x0000) ,(CKTDRA) ; CO = bus 

(0x0100) f (CKTDRB) ; CI - RS422 



DSKAST = 0x00, (DSKDRA) 
0x00,(DSKDRB) 
0x01,(DSKDRB) 
0x80,(0x0101) 
0x81,(0x0101) 
0x82,(0x0101) 

PTRAST = 0x00,(LSTDRA) 
0x01 , (LSTDRB) 
0x80,(0x0101) 
0x81,(0x0101) 

QUEAST = 0x00,(0x0000) 
0x00,(0x0000) 
0x80,(0x0101) 
0x81,(0x0101) 

DEFDID = (0x0101) 

DSPPAT = 1,2,3,4 

OSMLEN = (0x0600) 

COMPAT = 0xB8 

NMBSVC = 5 

NMBUFS = 20 



drv A= local HD 
drv B=local FD0 
drv C= local FD1 
drv D= remote HD 
drv E= remote FD0 
drv F=r emote FD1 
ptr A=lcl daisy 
ptr B=lcl matrix 
ptr C=rmt daisy 
ptr D=rmt matrix 
queue A=local 
queue B=local 
; queue C= remote A 
; queue D=remote B 
default=other master 
assgn ptrs to queues 
24K dynamic memory 
compatibility flags 
5 server processes 
20 IK disk buffers 



The generation of the second master operating 
system could be identical, except that all 
occurrences of network addresses (0x0100) and 
(0x0101) in the OSMASTER.PAR file would be 
reversed. Generation of the slave operating 
system would be very straightforward, and 
identical for both systems. 

If you study this example thoroughly until 
you understand the reason for every .GEN and 
.PAR file entry, you should have little 
trouble setting up your own "sysgens". 
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Sysgen Procedure To conclude this section, here is a suggested 

efon-hu-Ri-pn nrocedure for aeneratiny a new 
version of TurboDOS: 

1. Bring up a previous version of 8086 
TurboDOS. If this is your first attempt 
to generate an 8086 TurboDOS system, you 
may bring up CP/M-86 instead. However, if 
you are using CP/M, all disks will have to 
be in a format compatible with both CP/M 
and TurboDOS (e.g., eight-inch one-sided 
single-density with 128-byte sectors). 

2. Make a working copy of your TurboDOS dis- 
tribution disk. Do not use the original 
disk (in case something goes wrong). 
Insert the working diskette in a conven- 
ient disk drive. 

3. Using your favorite text editor, create or 
revise the file OSMASTER.GEN containing 
the names of the relocatable modules to be 
linked together. Generally, this will 
consist of the appropriate STDxxxxx stan- 
dard package plus selected additional 
modules and all required device drivers. 

4. Using your editor once again, create or 
revise the file OSMASTER.PAR containing 
any required patches. This may be omitted 
if no patches are desired. 

5. Using the command TLINK OSM ASTER, SXS., 
generate an executable master operating 
system in accordance with the .GEN and 
.PAR files. 

6. In a similar fashion, construct a new 
loader by creating or revising the files 
OSLOAD.GEN and OSLOAD.PAR, then using the 
command tt.ink OSLOAD^CIU) to generate the 
executable loader. 
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Sysgen Procedure 7. For a master/slave network system, con- 
struct a slave operating system in the 
same manner. Create or revise the files 
OSSLAVE.GEN and OSSLAVE.PAR, then use the 
command TLINK OSS LAVE.SYS to generate the 
down-loadable slave operating system. 

8. To test the newly-generated system, eject 
all disks other than your working disk 
(again, in case something goes wrong). 
Enter the command Q££Q£B. The new system 
should cold-start. If it fails to come up 
or to function properly, you will have to 
start over at step 1 and check your work 
carefully — there is most likely an error 
in one of your .GEN or .PAR files, or a 
"bug" in one of your drivers. 
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DISTRIBUTION This section explains the TurboDOS distribu- 
tion procedure in detail. It covers TurboDOS 
licensing requirements, and the obligations 
of licensed distributors, dealers, and end- 
users. It describes how to make up and 
serialize TurboDOS distribution disks. 

Although this section is of concern primarily 
to licensed TurboDOS distributors, we've 
included it here so that dealers and end- 
users can gain a better perspective on the 
overall distribution process. 



TurboDOS Licensing TurboDOS is a proprietary software product of 

Software 2000, Inc. As such, it is protected 
by law against unauthorized use and reproduc- 
tion. Authorization to use and/or reproduce 
TurboDOS is granted only by written license 
agreement. 



Legal Protection TurboDOS programs and documentation are copy- 
righted, which means it is against the law to 
make copies without express written authori- 
zation from Software 2000 to do so. 

The word "TurboDOS" is a trademark owned by 
Software 2000 and registered in Class 9 (com- 
puter software) and Class 16 (documentation) 
with the trademark offices of the United 
States and most of the developed countries of 
the free world. This means it is against the 
law to make use of the TurboDOS trademark 
without express written authorization from 
Software 2000. 

Software 2000 has licensed certain companies 
to distribute TurboDOS. Such distributors 
are authorized to use the TurboDOS trademark, 
and to reproduce, distribute, and sub-license 
TurboDOS programs and documentation to deal- 
ers and end-users. 
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User Obligations TurboDOS may be used only after the user has 

paid the required license fee, signed a copy 
of the TurboDOS end-user license agreement, 
and returned the signed agreement to the 
issuing TurboDOS distributor. Then, TurboDOS 
may be used only in strict conformance with 
the terms of the license. 

Each end-user license allows TurboDOS to be 
used on one specific computer system identi- 
fied by make, model, and serial number. The 
end-user license may not be transferred from 
one computer system to another, and expressly 
forbids copying programs and documentation 
except as required for backup purposes only. 

A separate license fee must be paid and a 
separate license signed for each computer 
system on which TurboDOS is used. Network 
slave computers that cannot operate stand- 
alone do not have to be licensed separately 
from the network master. (This would be the 
case, for example, if the slave computers 
have no local disk storage, or if TurboDOS is 
furnished in a form that cannot be run stand- 
alone on the slave computers.) However, 
networked computers that are also capable of 
stand-alone operation under TurboDOS must 
each be licensed separately. 



Dealer Obligations A dealer must sign a TurboDOS dealer agree- 
ment and return the signed agreement to the 
issuing distributor. Then, the dealer is 
permitted to purchase pre-serialized copies 
of TurboDOS programs and documentation from 
the distributor, and to resell them to end- 
users. Dealers may not reproduce TurboDOS 
programs or documentation for any purpose. 
Before delivering each copy of TurboDOS, the 
dealer must see to it that the end-user signs 
the TurboDOS end-user license agreement and 
returns it to the issuing distributor. 
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Distributor Each licensed TurboDOS distributor is provi- 

Obligations ded a master copy of TurboDOS relocatable 

modules and command programs on diskette. A 
distributor is allowed to reproduce and 
distribute copies of TurboDOS to dealers and 
end-users, but only in connection with 
certain specifically authorized hardware 
(usually manufactured or sold by the distri- 
butor). The distributor is required to 
serialize each copy of TurboDOS with a unique 
sequential magnetic serial number, and to 
register each serial number promptly with 
Software 2000. (Serialization is described 
in more detail below.) 

Each distributor is also provided with a 
master copy of TurboDOS documentation, either 
in camera-ready hardcopy or in ASCII files on 
disk. The distributor is responsible for 
reproducing the documentation and furnishing 
it with each copy of TurboDOS it issues. 

A distributor must require each dealer to 
sign and return a TurboDOS dealer agreement 
before issuing copies of TurboDOS to the 
dealer for resale. A distributor must 
require each end-user to sign and return a 
TurboDOS end-user license agreement before 
issuing a copy of TurboDOS directly to the 
end-user. 
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Serialization Each copy of TurboDOS is magnetically serial- 
ized with a unique serial number. Such 
serialization helps ensure that reproduction 
and distribution of TurboDOS is done in 
strict accordance with the required licensing 
and registration procedures, and facilitates 
tracing of unlicensed copies of the software. 

Each relocatable module of TurboDOS distribu- 
ted to a dealer or end-user has a magnetic 
serial number composed of two parts: 

. an orig in num ber that identifies the 
issuing distributor, and 

. a sequential unit JUimbeJL that uniquely 
identifies each copy of TurboDOS issued 
by that distributor. 

During system generation, the TLINK command 
verifies that all modules making up a Turbo- 
DOS configuration are serialized consistent- 
ly, and magnetically serializes the resulting 
executable version of TurboDOS accordingly. 

The relocatable modules on the master disk 
furnished to each licensed TurboDOS distribu- 
tor are partially serialized with an origin 
number only. Each distributor is provided a 
serialization program (SERIAL.CMD) that must 
be used to add a unique sequential unit num- 
ber to each copy of TurboDOS issued by the 
distributor. The TLINK command will not 
accept partially-serialized modules that have 
not been serialized with a unit number. Con- 
versely, the SERIAL command will not re- 
serialize modules that have already been 
fully serialized. 
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Technical Support Software 2000 maintains telephone and telex 

"hot-lines" to provide TurboDOS technical 
assistance to its distributors. These are 
unlisted numbers providing direct access to 
the authors of the TurboDOS operating system, 
and are furnished only to licensed TurboDOS 
distributors. We encourage distributors to 
take advantage of this service whenever tech- 
nical questions or problems arise in using or 
configuring TurboDOS. 

It is the responsibility of each licensed 
distributor to provide technical support to 
its dealers and end-user customers. Software 
2000 £A.njxp..£ assist dealers or end-users 
directly. Where exceptional circumstances 
seem to require direct contact between Soft- 
ware 2000 technical personnel and a dealer or 
end-user, this must be handled strictly by 
prior arrangement between Software 2000 and 
the distributor. 
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SERIAL Command 



Syntax 



Explanation 



Options 



The SERIAL command enables TurboDOS distribu- 
tors to magnetically serialize relocatable 
modules of TurboDOS for distribution. 



SERIAL srcefile destfile ;Unnn (options) I 
SERIAL ;Unnn (options) I 



The SERIAL command works exactly like the 
COPY command, and accepts exactly the Same 
arguments and options. However, SERIAL has 
the additional function of magnetically 
serializing relocatable modules as they are 
copied. SERIAL serializes files of type .REL 
(Z80 modules) and type .0 (8086 modules). 
Other files are copied without any change. 

The unit number must be specified on the 
command line as ;Unnn, where "nnn" represents 
a decimal unit number in the range 0-65535. 
Unit numbers must be assigned sequentially, 
starting with 1. Unit number is reserved 
by convention for in-house use by the distri- 
butor. 

SERIAL produces fully-serialized modules that 
are encoded with the distributor's origin 
number and the specified unit number. TLINK 
does not accept TurboDOS modules unless they 
have been fully serialized in this fashion. 



.Ppi^iPP- I EapJ.ana.fcj.op 



SERIAL accepts all COPY options, plus: 

;Unnn Relocatable modules (type .REL 
or .0) are magnetically serial- 
ized with unit number nnn, which 
must be a decimal integer in the 
range to 65535. This "option" 
is mandatory for SERIAL. 



3-6 



jP\3 r DOIX/O A ■» *¥ gvUV 

Implementor ■ s Guide 



SERIAL Ces&mand 
(Continued) 



Copyright 1984 by Software 2000, Inc. 
All rights reserved. 



Example 



I QAi SERlAli- 
0A:AUTLOD 
0A:AUTLOG 

OA-.SYSNIT 
0A> 



.0 copied to 0B:AUTLOD .0 
.0 copied to 0B:AUTLOG .0 

.0 copied to 0B:SYSNIT .0 






Error Messages 



SERIAL incorporates all COPY error mes- 
sages, plus: 

Unit number not specified 
Origin number violation 
File is already serialized 
Unexpected EOF in .0 or .REL file 
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PACKAGE Command The PACKAGE command lets you combine any 

collection of relocatable object modules into 
a single concatenated .0 file. 



Syntax I I 

I PACKAGE srcefile {destfile} I 



Explanation PACKAGE may be used to construct custom 

packages of TurboDOS modules, make additions 
or changes to the supplied sfDxxxxx packages/ 
pre-package collections of driver modules, 
and so forth. 

The "srcefile" argument specifies the name of 
an input file "srcefile. PKG" that lists the 
modules to be packaged. The "destfile" argu- 
ment specifies the name of the concatenated 
.0 file to be created. If "destfile" is 
omitted, then the "srcefile" argument is also 
used as the name of the output .0 file. 

If the .PKG file is found, it must contain 
the list of relocatable object modules (.0 
files) to be linked together. If the .PKG 
file is not found, then the PACKAGE command 
operates in an interactive mode. You are 
prompted by an asterisk * to enter a series 
of directives from the console. The syntax 
of each directive is: 



I objectfn {,objectfn> . . . {; comment} 



A null directive terminates the prompting 
sequence and causes processing to proceed. 

After obtaining the list of modules from the 
file or console, PACKAGE concatenates all of 
the modules together (displaying the name of 
each module as it is encountered) and writes 
the result to the output file. 
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Example 



! 0A> PACKAGE STDL.QADR 

* ; STDLOADR. PKG standard loader package 

* OSLOAD, LDRMSG , OSNTRY, FILMGR, FILSUP 

* FILCOM,BUFMGR,DSKMGR,DSKTBL r NONFIL 

* CONMGR,CONTBL,DSPSGL f COMSUB 
OSLOAD LDRMSG OSNTRY FILMGR FILSUP etc. 
0A} 



Error Messages 



File name missing from command 
Invalid input file name 
Non-privileged user 
Unexpected EOF in input file 
Disk is full 
Can't make output file 
Can't open input file 
No input files 
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Distribution Here is the procedure to be followed by dis- 
Procedure tributors when creating each copy of TurboDOS 

to be issued to a dealer or end-user: 

1. Assign a unique sequential unit number for 
this copy of TurboDOS, and register it 
immediately by filling out a serial number 
registration card (or agreed-to substi- 
tute) and mailing to Software 2000, Inc. 

2. Format a new disk, and label it with the 
following information clearly legible: 

. trademark TurboDOS R 

. version number (1.4x) 

. origin and unit numbers (oo/uuuu) 

. statutory copyright notice: 

Copyright 198x by Software 2000, Inc. 
All rights reserved. 

3. Use the SERIAL command to copy and serial- 
ize the appropriate files from your dis- 
tribution master disk to the new disk. 
Use the tables on the following page to 
guide you in determining what files to put 
on the new disk. 

IMPORTANT NOTEs Be absolutely certain 
that the new disk does not contain any 
unserialized modules or SERIAL.CMD! 

4. Using the new serialized disk, use the 
TLINK command to generate an executable 
loader and operating system. Follow the 
system generation procedure described in 
the previous section. 

5. In addition to the serialized disk, you 
should issue copies of TurboDOS documenta- 
tion and a start-up PROM (if applicable). 
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Distribution 

Procedure 

(Continued) 



.lowing table may be used for guidance 
taring TutDOfuo ux&K&> iul uiDttiwutivm 



The follow 

in prepaj 

In addition to the files shown, you need to 

include hardware-dependent driver modules and 

utility programs as appropriate. 



1 single-user 1 


single-user I 


multi-user 1 


! w/o_ spooler _!_ 


with spooler, J. 


networkina___ ! 


1 STDLOADR 


.0 


STDLOADR 


.0 


STDLOADR 


.0 1 


1 STDSINGL 


.0 


STDSINGL 


.0 


STDSINGL 


.0 1 


| — 




STDSP00L 


.0 


STDSPOOL 


.0 1 


| — 




- 




STDMASTR 


.0 I 


| — 




- 




STDSLAVE 


.0 1 


| - 




- 




STDSLAVX 


.0 1 


1 CPMSUP 


.0 


CPMSUP 


.0 


CPMSUP 


.0 1 


1 MPMSUP 


.0 


MPMSUP 


.0 


MPMSUP 


.0 1 


1 RTCNUL 


.0 


RTCNUL 


.0 


RTCNUL 


.0 1 


1 PATCH 


.0 


PATCH 


.0 


PATCH 


.0 1 


1 SUBMIT 


.0 


SUBMIT 


.0 


SUBMIT 


.0 1 


1 OSBOOT 


.0 


OSBOOT 


.0 


OSBOOT 


.0 1 


j — 




- 




NETREQ 


.0 i 


| — 




- 




NETFWD 


.0 1 


| - 




- 




QUEMGR 


.0 1 


| — 




- 




MSGFMT 


.0 1 


| — 




- 




NETSVC 


.0 1 


| - 




— 




CONREM 


.0 1 


1 AUTOLOAE 


l. CMD 


AUTOLOAD 


.CMD 


AUTOLOAD 


.CMD 1 


1 BACKUP 


.CMD 


BACKUP 


.CMD 


BACKUP 


.CMD 1 


| — 




- 




BATCH 


.CMD 1 


1 BOOT 


.CMD 


BOOT 


.CMD 


BOOT 


.CMD 1 


1 BUFFERS 


.CMD 


BUFFERS 


.CMD 


BUFFERS 


.CMD 1 


| — 




- 




CHANGE 


.CMD 1 


1 COPY 


.CMD 


COPY 


.CMD 


COPY 


.CMD 1 


1 DATE 


.CMD 


DATE 


.CMD 


DATE 


.CMD 1 


1 DELETE 


.CMD 


DELETE 


.CMD 


DELETE 


.CMD 1 


1 DIR 


.CMD 


DIR 


.CMD 


DIR 


.CMD 1 


1 DO 


.CMD 


DO 


.CMD 


DO 


.CMD 1 


1 DRIVE 


.CMD 


DRIVE 


.CMD 


DRIVE 


.CMD 1 


1 DUMP 


.CMD 


DUMP 


.CMD 


DUMP 


.CMD 1 
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Distribution 

Procedure 

(Continued) 



1 single-i 


aser 1 


single-user 


1 multi-user 


Lw/o_ spooler _ J 


_with spooler J network ina 


1 ERASEDIR.CMD 


ERASEDIR.CMD 


ERASEDIR.CMD 


I - 




- 




FIFO 


.CMD 


1 FIXDIR 


.CMD 


FIXDIR 


.CMD 


FIXDIR 


.CMD 


1 FIXMAP 


.CMD 


FIXMAP 


.CMD 


FIXMAP 


.CMD 


1 FORMAT 


.CMD 


FORMAT 


.CMD 


FORMAT 


.CMD 


1 LABEL 


.CMD 


LABEL 


.CMD 


LABEL 


.CMD 


I - 




- 




LOGOFF 


.CMD 


1 - 




_ 




LOGON 


.CMD 


1 




- 




MASTER 


.CMD 


1 OTOASM 


.CMD 


OTOASM 


.CMD 


OTOASM 


.CMD 


1 PRINT 


.CMD 


PRINT 


.CMD 


PRINT 


.CMD 


1 - 




PRINTER 


.CMD 


PRINTER 


.CMD 


1 - 




QUEUE 


.CMD 


QUEUE 


.CMD 


1 READPC 


.CMD 


READPC 


.CMD 


READPC 


.CMD 


1 




- 




RECEIVE 


.CMD 


1 RENAME 


.CMD 


RENAME 


.CMD 


RENAME 


.CMD 


I 




- 




SEND 


.CMD 


1 SET 


.CMD 


SET 


.CMD 


SET 


.CMD 


1 SHOW 


.CMD 


SHOW 


.CMD 


SHOW 


.CMD 


1 TASM 


.CMD 


TASM 


.CMD 


TASM 


.CMD 


1 TBUG 


.CMD 


TBUG 


.CMD 


TBUG 


.CMD 


1 TLINK 


.CMD 


TLINK 


.CMD 


TLINK 


.CMD 


1 TPC 


.CMD 


TPC 


.CMD 


TPC 


.CMD 


1 TYPE 


.CMD 


TYPE 


.CMD 


TYPE 


.CMD 


1 VERIFY 


.CMD 


VERIFY 


.CMD 


VERIFY 


.CMD 
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CODING CONVENTIONS 



This section is devoted to in-depth discus- 
sion of TurboDOS internal coding conventions, 
aimed at the systems programmer writing hard- 
ware-dependent drivers or resident processes. 
All coding examples and driver listings in 
this document make use of the TurboDOS 8086 
assembler TASM. 



Undefined External 
References 



To allow various TurboDOS modules to be in- 
cluded or omitted at will/ TLINK auto- 
matically resolves all undefined external 
references to the default names "UndCode" 
(for code references) and "UndData" (for data 
references). The common subroutine module 
COMSUB contains the following: 



1 LOC 


Data* 


;data segment 1 


1 UndData:: 




; undefined data 1 


1 WORD 


0,0 




! LOC 


Code# 


;code segment 1 


1 UndCode : : 




; undefined code 1 


1 XOR 


AL f AL 


;zero AL & flags 1 


1 RET 




; return 1 



Thus, it is always safe to load or call an 
external name, whether or not it is present 
at TLINK time. It is bad form to store into 
an undefined external name, however 1 
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Memory Allocation 



A common memory management module MEMMGR 
provides dynamic allocation and deallocation 
of memory space required for disk and message 
buffers, print queues, file and record locks, 
do-file nesting, and so forth. TurboDOS 
reserves a region of memory for such dynamic 
workspace, located immediately above the 
TurboDOS resident. The length of this area 
(in paragraphs) is determined by the patch- 
able parameter OSMLEN. Memory segments are 
allocated downward from the top of the 
reserved region. Deallocated segments are 
concatenated with any neighbors and threaded 
on a free-memory list. A best-fit algorithm 
is used to reduce memory fragmentation. 

Allocation and deallocation requests are 
coded in this manner: 



1 ;code 


to allocate a memory segment 




MOV 


BX,=36 


;BX=segment size 




CALL 


ALLOC* 


; allocate segment 




TEST 


AL,AL 


;alloc successful? 




JNZ 


ERROR 


;NZ -> not enuf mem 




PUSH 

• 


BX 


;else, BX=&segment 


1 ;code 


• 

to deallocate a 


memory segment 




POP 


BX 


;BX=&segment 




CALL 


DEALOC* 


7 deallocate segment 



ALLOC* prefixes each allocated segment with a 
word containing the segment length, so that 
DEALOC* can tell how much memory is to be 
deallocated. ALLOC* does not zero the newly- 
allocated segment. 
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List Processing 



TurboDOS maintains its dynamic structures as 
cnceaueu usts wufi uiuiic^Liwima. xahRw^v.^" 
This technique permits a node to be added or 
deleted anywhere in a list without searching. 
The list head and each list node have a two- 
word linkage (forward and backward pointers) . 

List manipulation is coded in this manner i 



LOC Data* ;data segment 
;list head (linkage initialized empty) 
LSTHED: WORD LSTHED ; forward pointer 

WORD LSTHED ; backward pointer 

;list node (linkage not initialized) 
LSTNOD: WORD ; forward pointer 
WORD ; backward pointer 
RES 128 ; contents of node 

LOC Code* ; program segment 
;code to add node to end of list 

MOV BX,&LSTHED ;BX=Shead 
MOV DX,&LSTNOD ;DX=&node 
CALL LNKEND* ;link to list end 

;code to unlink node from list 

MOV BX,&LSTNOD ;BX=&node 
CALL UNLINK* ; unlink node 

;code to add node to beginning of list 
MOV BX f &LSTHED ;BX=&head 
MOV DX,&LSTNOD ;DX=&node 
CALL LNKBEG* ;link to list beg 
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Task Dispatching 



TurboDOS incorporates a flexible, efficient 
mechanism for dispatching the 8086-family CPU 
among various competing processes. In coding 
drivers for TurboDOS, you must take extreme 
care to use the dispatcher correctly in order 
to attain maximum system performance. 

The dispatcher allows one process to wait for 
some event (for example, data-available or 
seek-complete) while allowing other processes 
to use the processor. For each such event, 
you must define a three-word structure called 
a "semaphore". 

A semaphore consists of a count-word followed 
by a two-word list head. The count-word is 
used by the dispatcher to keep track of the 
status of the event. (At present, only the 
LSB of the count word is used, supporting 
counts in the range -128 to +127.) The list 
head anchors a threaded list of processes 
waiting for the event to occur. 

Two primitive operations operate on a sema- 
phore: waiting for the event to occur 
(WAIT#), and signalling that the event has 
occurred (SIGNAL*). They are coded in this 
following manner: 



;this semaphore represents some event 
EVENT: WORD ; semaphore count 

WORD EVENT+2 ; semaphore f-ptr 
WORD EVENT+2 ; semaphore b-ptr 

;wait for the event to occur 

MOV BX,&EVENT ;BX=& semaphore 
CALL WAIT* ;wait for event 

; signal that event has occurred 

MOV BX,&EVENT ;BX=&sempahore 
CALL SIGNAL* ; signal event 
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Task Dispatching 
(Continued} 



Whenever a process waits on a semaphore, 
WAIT! decrements the semaphore's count-word. 
Thus, a negative count -N signifies that 
there are N processes waiting for the event 
to occur. Whenever an event is signalled, 
SIGNAL* increments the semaphore count-word 
and awakens the process that has been waiting 
longest. 

If an event is signalled but no process is 
waiting for it, then SIGNAL* increments the 
count-word to a positive value. Thus, a 
positive count N signifies that there have 
been N occurrences of the event for which no 
process was waiting. In this case, the next 
N calls to WAIT* on that semaphore will 
return immediately without waiting. 

Sometimes it is necessary for a process to 
wait for a specific time interval (for exam- 
ple, a motor-start delay or carriage-return 
delay) rather than for a specific event. 
TurboDOS provides a delay facility (DELAY*) 
that permits other processes to use the CPU 
while one process is waiting for such a timed 
delay. Delay intervals are specified as some 
number of "ticks". A tick is an implementa- 
tion-defined interval, usually 1/50 or 1/60 
of a second. Delays are coded thus: 



; delay for one-tenth of a second 

MOV BX,=6 ;BX=delay in ticks 

CALL DELAY* ; delay process 



Accuracy of delays is usually plus-or-minus 
one tick. A delay of zero ticks may be 
specified to relinquish the processor to 
other processes on a "courtesy" basis. 

All driver delays should be accomplished via 
WAIT* or DELAY*, ne.£ejL by spinning in a loop. 
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Interrupt Service 



Dispatching is especially efficient when used 
with interrupt-driven devices. Usually, the 
interrupt service routine just calls SIGNAL* 
to signal the interrupt-associated event. 

Most interrupt service routines should exit 
via the usual IRET instruction. However, 
some periodic interrupt (usually a 50 or 60 
hertz clock interrupt) should have an inter- 
rupt service routine that exits by jumping to 
the ^ispatcne!. enfrypoint ISRXIT* to p rov i<je 
periodic time-slicing of processes. To avoid 
excessive dispatcher overhead, don't use 
ISRXIT* more than about 60 times per second. 

Before calling any TurboDOS support routine 
(such as SIGNAL*) or referencing any DS- 
relative data, an interrupt service routine 
must call the subroutine GETSDS* to set up 
register DS. 

A simple interrupt service routine might be 
coded like this: 



1 DEVISR: POSH 


AX 




•save registers 1 


1 PUSH 


BX 




n m 1 


1 PUSH 


CX 




, N N I 


1 PUSH 


DX 




, n n I 


1 PUSH 


DS 




, n n | 


1 CALL 


GETSDS* | 


?get system DS 1 


1 MOV 


BX, 


&EVENT 


;BX=&semaphore 1 


1 CALL 


SIGNAL* t 


? signal event 1 


1 MOV 


DX, 


&EOIR , 


?DX=&end-of-int 1 


1 MOV 


AX, 


= INTN 


?AX=interrupt# 1 


1 OUT 


DX, 


AX 


preset interrupt 1 


1 POP 


DS 




^restore registers 1 


1 POP 


DX 




, n n i 


1 POP 


CX 




, M HI 


1 POP 


BX 




, n ii | 


1 POP 


AX 




, n n 1 


1 IRET 






\ return from int. 1 
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Devices incapable of interrupting the CPU 
have to be polled by the driver. The dis- 
patcher maintains a threaded list of poll 
routines, and executes them every dispatch. 
The function of each poll routine is to check 
the status of its device, and to signal the 
occurrence of some event (for example, data- 
available) when it occurs. The routine 
LNKPOL# links a poll routine onto the poll 
list, and UNLINK# removes it. 

A poll routine must be coded so that it will 
not signal the occurrence of a particular 
event more than once. The best way to assure 
this is for the poll routine to unlink itself 
from the poll list as soon as it has signal- 
led the event. An example: 



1 EVENT: 


WORD 


; semaphore ! 




WORD 


EVENT+2 1 




WORD 


EVENT+2 1 


1 ;driver 


waits 


for event 1 




MOV 


DX,&POLNOD ;DX=&poll node 1 




CALL 


LNKPOL# ; activate poll rtn 1 




CALL 


POLRTN ; optional pretest 1 




MOV 


BX,&EVENT ;BX=&semaphore I 




CALL 

• 
• 


WAIT* ;wait for event 1 


1 ;poll routine 


signals event when detected 1 


1 POLNOD: 


WORD 


;poll rtn linkage 1 




WORD 


; " " " 1 


1 POLRTN : 


IN 


AL,=STAT ;AL=device status 1 




TEST 


AL,=MASK ;did event occur? 1 




JZ 


X ;if not, exit 1 




MOV 


BX,&EVENT ;BX=&semaphore 1 




CALL 


SIGNAL* ; signal event 1 




MOV 


BX,&POLNOD ;BX=&poll node 1 




CALL 


UNLINK* ;unlink poll rtn 1 


I X: 


RET 


;all done 1 
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Mutual Exclusion 



TurboDOS is fully re-entrant at the process 
and kernel levels. However, most driver 
modules are not coded re-entrantly (since 
most peripheral devices can only do one thing 
at a time). Consequently, most drivers must 
make use of a mutual-exclusion interlock to 
prevent TurboDOS from invoking them re-ent- 
rantly. 

This is very easy to accomplish using the 
basic semaphore mechanism of the dispatcher. 
It is only necessary to define a semaphore 
with its count-word initialized to 1 (instead 
of 0). Mutual exclusion may then be accom- 
plished by calling WAIT* upon entry and 
SIGNAL* upon exit. An example: 



;mutual-exclusion semaphore 

MXSPH: WORD 1 ;count-word=l! 

WORD MXSPH+2 

WORD MXSPH+2 

DRIVER: MOV BX,&MXSPH ;BX=&semaphore 
CALL WAIT* ;wait if in-use 



MOV BX,&MXSPH ;BX=& semaphore 
CALL SIGNAL* ; unlock mut-excl 
RET /done 
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Sample Driver 
Usinq Interrupts 



Here is a simple device driver for an inter- 
rupt-driven serial input device- It illus- 
trates coding techniques discussed so far: 



1 MXSPH: 


WORD 


1 


MX semaphore 1 




WORD 


MXSPH+2 1 




WORD 


MXSPH+2 ! 


1 RDASPH: 


WORD 


;RDA semaphore 1 




WORD 


RDASPH+2 1 




WORD 


RDASPH+2 1 


1 CHRSAV: 


BYTE 


; saved input char 1 


1 ; device 


driver main code 1 


1 INPDRV: 


:MOV 


BX f &MXSPH ;BX=&MXsemaphore ! 




CALL 


WAIT* ;lock MX 1 




STI 


;need ints enabled 1 




MOV 


BX,&RDASPH ;BX=& semaphore 1 




CALL 


WAIT* ;wait data avail 1 




PUSH 


CHRSAV ; stack input char 1 




MOV 


BX,&MXSPH ;BX=&MXsemaphore 1 




CALL 


SIGNAL* ; unlock MX 1 




POP 


AX ; return AL=char i 




RET 


;done 1 


1 ; interrupt service routine 1 


1 INPISR: 


:PUSH 


AX i 


save registers 1 




PUSH 


BX j 


n n 1 




PUSH 


CX ; 


, n n | 




PUSH 


DX j 


, n it 1 




PUSH 


DS 


, it n 1 




CALL 


GETSDS* j 


•get system DS 1 




IN 


AL,=INPUT ;get input char I 




MOV 


CHRSAV, AL ;save for driver 1 




MOV 


BX,&RDASPH ;BX=&semaphore 1 




CALL 


SIGNAL* , 


} signal data avail 1 




POP 


DS 


^restore registers I 




POP 


DX 


,11 HI 




POP 


CX 


n n 1 




POP 


BX 


« " 1 




POP 


AX 


■ " n 1 




IRET 




^return from int. 1 
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Sample Driver 
Using Polling 



Here is a simple device driver for non-inter- 
rupting serial input device. It illustrates 
how polling is used: 



1 MXSPH: 


WORD 


1 ;MX semaphore 1 




WORD 


MXSPH+2 1 




WORD 


MXSPH+2 1 


1 RDASPH: 


WORD 


;RDA semaphore 1 




WORD 


RDASPH+2 1 




WORD 


RDASPH+2 1 


1 CHRSAV: 


BYTE 


; saved input char 1 


1 ;device 


driver main code 1 


1 INPDRV: 


:MOV 


BX,&MXSPH ;BX=&MXsemaphore 1 




CALL 


WAIT# ;lock MX 1 




MOV 


DX,&POLNOD ;DX=&pollnode 1 




CALL 


LNKPOL# ; activate poll rtn 1 




CALL 


POLRTN ; optional pretest 1 




MOV 


BX r &RDASPH ;BX=&semaphore 1 




CALL 


WAIT# ;wait data avail 1 




PUSH 


CHRSAV ; stack input char 1 




MOV 


BX r &MXSPH ;BX=&MXsemaph 1 




CALL 


SIGNAL# ;unlock MX 1 




POP 


AX ; return AL=char 1 




RET 


;done 1 


1 ; device 


poll 


routine with linkage 1 


1 POLNOD: 


WORD 


;poll rtn linkage 1 




WORD 


1 


1 POLRTN: 


IN 


AL,=STAT ;get device status 1 




TEST 


AL,=MASK ;data available? 1 




JZ 


X ;if not, exit 1 




IN 


AL,=DATA ;get input char 1 




MOV 


CHRSAV, AL ;save for driver 1 




MOV 


BX,&RDASPH ;BX=&semaphore 1 




CALL 


SIGNAL* ; signal data avail 1 




MOV 


BX,&POLNOD ;BX=&pollnode 1 




CALL 


UNLINK* ;unlink poll rtn 1 


1 X: 


RET 


;done 1 



4-10 



TurboDOS 1.4 8086 
Implementor ■ s Guide 



(CODING CONVENTIONS 

Inter-Process 
Messages 



Copyright 1984 by Software 2000, Inc. 
All rights reserved. 



Inter-Process 
Messages 



To pass messages from one process to another, 
a five-word structure called a "message node* 1 
is used. A message node consists of a three- 
word semaphore followed by a two-word message 
list head. Routines are provided for sending 
messages to a message node (SNDMSG#), and 
receiving messages from a message node 
(RCVMSGt). Typically, the sending process 
allocates a memory segment in which to build 
the message, and the receiving process deal- 
locates the segment after reading the mes- 
sage. The first two words of each message 
must be reserved for a list-processing link- 
age. Coding is done in this manner: 



1 ;message node 






1 MSGNOD: WORD 


! 


•semaphore part 


1 WORD 


MSGNOD+2 ] 


it n 


1 WORD 


MSGNOD+2 t 


m n 


1 WORD 


MSGNOD+6 , 


^message list head 


1 WORD 


MSGNOD+6 , 


, n . n n 


1 ;one process 


allocates/builds/sends msg 


1 MOV 


BX,=12+4 


?BX=message size+4 


1 CALL 


ALLOC* 


• r allocate segment 


1 PUSH 


BX 


?save &segment 


I • 
1 • 




jrbuild msg in seg 


1 POP 


DX 


;DX=&segment 


1 MOV 


BX,&MSGN01 


[) ;BX=&msgnode 


1 CALL 


SNDMSG* 


;send message 


1 ; other process reads/deallocates message 


1 MOV 


BX,&MSGN01 


D ;BX=&msgnode 


1 CALL 


RCVMSG* 


; receive message 


1 PUSH 


BX 


;save &segment 


1 • 




;process message 


1 POP 


BX 


;BX=&segment 


1 CALL 


DEALOC* 


Reallocate seg 
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Console Routines 



TurboDOS includes several handy console I/O 
subroutines which may be called from within 
driver modules as illustrated: 



1 ;raw console 


I/O routines 


1 CALL 


CONST* 


;get status in AL 


I TEST 


AL,AL 


; input char avail? 


1 JZ 


_x 


;if not r exit 


1 CALL 


CONIN* 


;get input in AL 


1 CALL 


UPRCAS* 


;make upper-case 


I MOV 


CL,AL 


;char to CL 


1 CALL 


CONOUT* 


; output char in CL 


1 ;message output routines 


1 ;message must 


be null- 


terminated 


1 CALL 


DMS# 


; output following 


1 MSG: BYTE 


"This is 


a test message\0" 


1 MOV 


BX r &MSG 


;BX=&message 


1 CALL 


DMSBXt 


; output msg *BX 


1 ;binary-to-de 


cimal output routine 


1 MOV 


BX, =31416 ;BX=word value 


1 CALL 


DECOUT* 


;displays decimal 



Sign-On Message 



You may add your own custom sign-on message 
to TurboDOS. Your message will be displayed 
at cold-start immediately following the nor- 
mal TurboDOS sign-on and copyright notice. 

Your sign-on message must be coded as an 
ASCII character string terminated with a $ 
delimiter, and labelled with the public entry 
symbol USRSOM. An example: 



USRSOM::BYTE 
BYTE 
BYTE 
BYTE 



OxOD, OxOA 
"Implementation by " 
"Trigon Computer Corp. 
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Resident Process 



You can code a resident process that runs in 
the background concurrent with other system 
activities, and link it into TurboDOS. The 
create-process subroutine CRPROC* may be 
called to create such a process at cold-start 
as shown: 



1 HDWNIT: 


:MOV 


BX,=128 ;BX=workspace size 1 




CALL 


ALLOC* ;alloc workspace 1 
;BX=&workspace 1 




MOV 


DX,&MYPROC ;DX=&entrypoint 1 




CALL 

• 
• 


CRPROC# ; create process 1 


1 MYPROC: 


INC 


COUNT [DI] ; increment count 1 




MOV 


DX, =60*60 ;ticks/minute 1 




MOV 


CL,=2 ;T-function 2 1 




CALL 


OTNTRY* ; delay 1 minute 1 




JMP 


MYPROC ;loop forever 1 



CRPROC# automatically allocates a TurboDOS 
process area (address appears in register SI) 
and a stack area (address appears in SP). If 
the process requires a re-entrant workspace, 
it should be allocated with ALLOC* and passed 
to CRPROC* in BX (as shown above), and will 
appear to the new process in register DI. 

The resident process must make all operating 
system requests by calling OCNTRY* or OTNTRY* 
with a C-function or T-function number in 
register CL. It mjisi nafc. execute INT OxEO or 
INT OxDF, nor make direct calls on kernel 
routines such as WAIT*, SIGNAL*, DELAY*, 
SNDMSG*, RCVMSG*, ALLOC*, and DEALOC*. 
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Resident Process 
(Continued) 



A resident process is not attached to a con- 
sole, so any console I/O requests will be 
ignored. 

You can do file processing within a resident 
process, using the normal C-functions open, 
close, read, write, and so forth, called via 
OCNTRY#. First, however, you must remember 
to warm-start with C-f unction (OCNTRYt), 
and then log-on with T-f unction 14 (OTNTRY#). 

A resident process must always be coded to 
preserve the contents of index register SI, 
which Turbodos relies upon as a pointer to 
its process area. The process may use all 
other registers as desired. 



Dser-De fined 
Function 



The User-Defined Function (T-function 41) 
provides a means of adding your own special 
functions to the normal TurboDOS repertoire 
of C-functions and T-functions. To do this, 
you simply create a function processor sub- 
routine with the public entrypoint symbol 
USRFCN. 

Whenever a program invokes T-function 41, 
TurboDOS transfers control to your USRFCN 
routine. On entry, ES:CX contains the 
address of the 128-byte record area passed 
from the caller's current DMA address, and 
registers BX and DX contain whatever values 
the caller loaded into them. Your USRFCN 
routine may return data to the caller in the 
128-byte record area (address in CX at entry) 
and in any of the registers AL-BX-CX-DX. 

Architecturally, your USRFCN routine is in- 
side the TurboDOS kernel. Consequently, it 
may call kernel subroutines directly. Any 
calls to C-functions and T-functions must 
therefore be made by means of two special 
recursive entrypoints: XCNTRY* and XTNTRY#. 
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DRIVER INTERFACE This section explains how to code hardware- 

uepciiueiiu uevite uixvcl uiuuuj.cs/ emu ^tcocm-o 

formal interface specifications for each 
category of driver required by TurboDOS. 

Following this section is a large appendix 
that contains assembler source listings of 
actual driver modules. The sample drivers 
cover a wide range of peripheral devices, and 
provide an excellent starting point for your 
driver development work. 



General Notes 



Drivers modules are coded with standard pub- 
lic entrypoint names, and linked to TurboDOS 
using the TLINK command. You may package 
your drivers into as many or few separate 
modules as you like. In general, it is 
easier to reconfigure TurboDOS for a variety 
of devices if the driver for each device is 
packaged as a separate module. 

TurboDOS is designed to accomodate multiple 
disk, console, printer, and network drivers. 
For disk drivers, for instance, the DSKAST is 
normally set up to refer to disk driver 
entrypoints DSKDRAt, DSKDRBt, DSKDRC#, and so 
forth. Each disk driver should be coded with 
the public entrypoint DSKDIL-. TLINK automa- 
tically maps successive definitions of such 
names by replacing the trailing __ by A, B, C, 
etc. The same technique may be used for 
console, printer, and network driver entry- 
points. 

You must code driver routines to preserve CS, 
DS, SS, SP, SI and DI registers, but you may 
use other registers as desired. 
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Initial ization 



Hardware initialization and interrupt vector 
set-up should be performed in an initializa- 
tion routine labelled with the public entry 
symbol HDWNIT::. TurboDOS calls this routine 
during cold-start with interrupts disabled. 

Your HDWNIT:: routine mu&fc not enable inter- 
rupts or make calls to WAIT* or DELAY*. In 
most cases, HDWNIT:: will contain a series of 
calls to individual driver initialization 
subroutines contained in other modules. 



Memory Table 



All 8086 TurboDOS systems must include a 
table that specifies the size and layout of 
main memory. The table must be labelled with 
the public symbol MEMTBL. It must begin with 
a byte value that specifies the number of 
discontiguous regions of main memory (up to 
eight), followed by two words for each region 
which specify the base address and length of 
the segment (both in paragraphs). The first 
segment in the table must be large enough to 
contain the resident portion of 8086 TurboDOS 
plus the dynamic workspace (given by OSMLEN). 

The following example illustrates the simple 
case of a system with 256K of contiguous 
memory starting at zero: 



1 MODULE "MEMTBL" 


;module ident 


1 LOC 


Data* 


;data segment 


1 MEMTBL:: 




; memory spec table 


1 BYTE 


1 


;just one region 


1 WORD 


0x40 


;base (paragraph) 


1 , WORD 


0x4000- 


-0x40 ;length (para) 


1 END 







Note that the first 0x40 paragraphs (IK 
bytes) are reserved for 8086 interrupt 
vectors and must not be included in MEMTBL. 
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Console Driver 



A console driver should be labelled with the 
public entry symbol CONDIL.. A console number 
"(from CONAST) is passed in register CH. The 
driver must perform a console I/O operation 
according to the operation code passed in 
register DL: 

1 PL?- ^ J Ptf Ac £ j.pn , — _! 



Return status in AL, char in CL 

1 Return input character in AL 

2 Output character passed in CL 

8 Enter error-message mode 

9 Exit error-message mode 

10 Conditional output char in CL 



If DL=0, the driver determines if a console 
input character is available. If no char- 
acter is available, the driver returns AL=0. 
If an input character is available, the 
driver returns AL=-1 and the input character 
in CL, &y± jQii§£ npjt "consu me" £te Phajapjbej . 
TurboDOS depends upon this look-ahead capa- 
bility to detect attention requests. The 
driver must not dispatch (via WAIT* or 
DELAY*) when processing a DL=0 call. 

If DL=1, the driver returns an input char- 
acter in AL (waiting if necessary). 

If DL=2, the driver displays the output char- 
acter passed in CL (waiting if necessary). 

If DL=8, the driver prepares to display a 
TurboDOS error message; if DL=9, it reverts 
to normal. TurboDOS always precedes each 
error message with an DL=8 call and follows 
it with an DL=9 call. This gives the driver 
an opportunity to take special action (25th 
line, reverse video, etc.) for error 
messages. For simple consoles, the driver 
should output CR-LF in response to DL=8 or 9. 
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Console Driver If DL=10, the driver determines whether or 
(Continued) not it can accept a console output character 

without dispatching (via WAIT* or DELAY*). 
If so, it outputs the character passed in CL, 
and returns AL=-1 to indicate that the char- 
acter was accepted. However, if the driver 
cannot accept a console output character 
without dispatching, it returns AL=0 to 
indicate that the character was not accepted; 
TurboDOS will then make an DL=2 call to 
output the same character. This special 
conditional output call is used by TurboDOS 
to optimize console output speed by avoiding 
certain dispatch-related overhead whenever 
possible. 

You should make a special effort to code the 
console driver to execute the minimum number 
of instructions possible, especially func- 
tions 0, 2, and 10. Excessive use of subrou- 
tine calls, stack operations, and other time- 
consuming coding techniques can make the 
difference between running the console device 
at full rated speed or something less. Study 
the sample driver listings in the appendix 
with this in mind. 
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Printer Driver A printer driver should be labelled with the 

public entry symbol LSTDIL_. A printer number 
'(from PTRAST) "is passed in register CH. The 
driver must perform a printer output opera- 
tion according to the operation code passed 
in register DL: 



DL=~ - J Function — _____ 

2 Print character passed in CL 

7 Perform end-of-print-job action 



If DL=2, the driver prints the output charac- 
ter passed in CL (waiting if necessary). 

If DL=7, the driver takes any appropriate 
end-of-print-job action. This is quite 
hardware-dependent, and may include slewing 
to top-of-form, homing the print head, 
dropping the ribbon, and so forth. 
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Disk Driver 



A disk driver should be labelled with the 
public entry symbol DSKDIL.. The driver per- 
forms the physical disk operation specified 
by the Physical Disk Request (PDR) packet 
whose address is passed by TurboDOS in index 
register SI. The structure of the PDR packet 
is: 



. Of. £ set. J. £pAteJiJ;.s. 



;phys 

0[SI 

ItSI 

2[SI 

4ISI 

6tSI 

8tSI 

10ESI 

12fSI 

14[SI 

;copy 

16ISI 

17ESI 

19ISI 

20[SI 

21 [SI 

23ESI 

25ESI 



ical dis 
BYTE 
BYTE 
WORD 
WORD 
WORD 
WORD 
WORD 
WORD 
WORD 
of disk 
BYTE 
WORD 
BYTE 
BYTE 
WORD 
WORD 
WORD 



k request 
OPCODE 
DRIVE 
TRACK 
SECTOR 
SECCNT 
BYTCNT 
DMAOFF 
DMABAS 
DSTADR 
specif ica 
BLKSIZ 
NMBLKS 
NMBDIR 
SECSIZ 
SECTRK 
TRKDSK 
RESTRK 



(PDR) packet 
operation code 
drive (base 0) 
track (base 0) 
sector (base 0) 
tsectors to rd/wr 
#bytes to rd/wr 
DMA offs to rd/wr 
DMA base to rd/wr 
DST address 
tion table (DST) 
;block size (3-7) 
;#blocks on disk 
;#directory blocks 
;sector size (0-7) 
;sectors per track 
;tracks on disk 
/reserved tracks 



The operation to be performed by the driver 
is specified in the first byte of the PDR 
packet (OPCODE) as follows: 



J2E£QEE~L_„ 



— F JAnsJEipn — 



Read sectors from disk 

1 Write sectors to disk 

2 Determine disk type r return DST 

3 Determine if drive is ready 

4 Format track on disk 
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Disk Driver 



If OPCODE=0, the driver reads_SECCNT physical 
sectors (or equivalentiy, BYtCNt bytes) into 
DMAOFF/DMABAS, starting at TRACK and SECTOR 
on DRIVE. The driver returns AL=0 if the 
operation is successful, or AL = -1 if an 
unrecoverable error occurs. TurboDOS may 
request multiple consecutive sectors to be 
read, but will never request an operation 
that extends past the end of the track. 

If OPCODE=l, the driver writes SECCNT physi- 
cal sectors (or BYTCNT bytes) from 
DMAOFF/DMABAS, starting at TRACK and SECTOR 
on DRIVE. The driver returns AL=0 if the 
operation is successful, or AL=-1 if an 
unrecoverable error occurs. TurboDOS may 
request multiple consecutive sectors to be 
written, but will never request an operation 
that extends past the end of the track. 

If OPCODE=2, the driver must determine the 
type of disk mounted in DRIVE, and must 
return, in the DSTADR field of the PDR 
packet, the address of an 11-byte disk speci- 
fication table (DST) structured as follows: 



Offset. J, , Pe sc ri P fcjlpn — 





1-2 

3 

4 

5-6 

7-8 

9-10 



block size (3=1K,4=2K,. . . ,7=16K) 
total number of blocks on disk 
number of directory blocks 
sector size (0=128, ... ,7=16K) 
number of sectors per track 
number of tracks on the disk 
number of reserved (boot) tracks 



The first byte of the DST (BLKSIZ) specifies 
the allocation block size in bits 2-0. In 
addition, bit 7 is set if the disk is fixed 
(non-removable), and bit 6 is set if file 
extents are limited to 16K (EXM=0) . 
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Disk Driver The driver returns AL=-1 if the operation is 
(Continued) successful, or AL=0 if the drive is not ready 

or the disk type is unrecognizable. On suc- 
cessful return, TurboDOS moves a copy of the 
DST into 16LSI] through 26ESI], where it is 
available for subsequent operations. 

If OPCODE=3, the driver determines whether 
DRIVE is ready, and returns AL=-1 if it is 
ready or AL=0 if not. 

If OPCODE=4, the driver formats (initializes) 
TRACK on DRIVE, using hardware-dependent 
formatting information at DMAOFF/DMABAS (put 
there by the FORMAT command). The driver 
returns AL=0 if successful, or AL=-1 if an 
unrecoverable error occurs. 
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Network Driver 



A network circuit driver should be labelled 
with the public entry symbol CKTDR_. A mes- 
sage buffer address is passed in register DX. 
The driver must either send or receive a 
network message, according to the operation 
code passed in register CL: 

Receive message into buffer at DX 

1 Send message from buffer at DX 



If CL=0, the driver receives a network mes- 
sage into the message buffer whose address is 
passed in DX (waiting if necessary). If a 
message is received successfully, the driver 
returns AL=0. If an unrecoverable malfunc- 
tion of any remote processor is detected, the 
driver returns AL=-1 with the network address 
of the crashed processor in DX. 

If CL=1, the driver sends a network message 
from the message buffer whose address is 
passed in DX. If the message is sent suc- 
cessfully, the driver returns AL=0. If the 
message could not be sent because of an unre- 
coverable malfunction of the destination 
processor, the driver returns AL=-1 with the 
network address of the crashed processor in 
DX. 

The structure of a network message buffer is 
shown on the next page. The first two words 
of the buffer are reserved for a linkage used 
by TurboDOS, and should be ignored by the 
driver. The 11-byte message header and 
variable-length message body should be sent 
or received over the circuit. The driver 
needs to look at only the first two header 
fields (MSGLEN and MSGDID) and possibly the 
last field (MSGFCD). 
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Network Driver 
(Continued) 



1 ; message buffer format 


1 WORD 


• 


; linkage (ignored) 


1 WORD 


? 


. n n 


1 ; 11-byte message header 


1 BYTE 


MSGLEN 


;msg length 


1 WORD 


MSGDID 


;destination addr 


1 BYTE 


MSGPID 


;process id 


1 WORD 


MSGSID 


; source addr 


1 WORD 


MSGOID 


;originator addr 


1 BYTE 


MSGOPR 


;orig'r process id 


1 BYTE 


MSGLVL 


; forwarding level 


1 BYTE 


MSGFCD 


;msg format code 


1 ; variable-length body 




1 RES 


7 


;registers 


1 RES 


1 


;user # and flags 


1 RES 


37 


; optional FCB data 


1 RES 


128 


; optional record 



The message format code field MSGFCD contains 
bit-encoded flags that define the format and 
context of each network message. This field 
may be ignored by most simple drivers, but 
its contents may be useful in complex network 
environments. Encoding of MSGFCD is: 



BiJL J Meaning., 



first message of session 

1 last message of session 

2 continuation message follows 

3 request includes FCB data 

4 request includes record data 

5 reply includes FCB data 

6 reply includes record data 

7 this is a reply message 
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Network Driver The length field MSGLEN represents the number 

l Continued! 1 r\-f KwJ-«ae i r> 4-V»£» moeoaAQ inn! n/^inn 1-Ko Koa/^ar 

and body (but excluding the linkage). On a 
receive request (CL=0), TurboDOS presets 
MSGLEN to the maximum allowable message 
length, and expects MSGLEN to contain the 
actual message length on return. On a send 
request (CL=1), TurboDOS presets MSGLEN to 
the actual length of the message to be sent. 

In a master/slave network, it is often desir- 
able for the circuit driver in the master to 
periodically "poll" the slave processors on 
the circuit to detect any slave malfunctions 
quickly and to effect recovery. If the 
driver reports that a slave has crashed (by 
returning AL=-1 and DX=network-address) , then 
the circuit driver must not accept any fur- 
ther messages from that slave until TurboDOS 
has completed its recovery process. 

TurboDOS signals the driver that such recov- 
ery is complete by sending a dummy message 
destined for the slave in question with a 
length of zero. The driver should not actu- 
ally send such a message to the slave, but 
could initiate whatever action is appropriate 
to reset the slave and download a new copy of 
the slave operating system. 

A slave must request an operating system 
download by sending a special download re- 
quest message to the master (usually done by 
a bootstrap routine). The download request 
message consists of a standard 11-byte header 
(with MSGPID, MSGOID and MSGFCD zeroed) fol- 
lowed by a 1-byte body containing a "download 
suffix" character. The master processor 
addressed by MSGDID will return a reply mes- 
sage whose 128-byte body is the first record 
of the download file OSSLAVEx.SYS (where "x" 
is the specified download suffix). 
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Network Driver The slave continues to send download request 
(Continued) messages and to receive successive download 

records until it receives a short reply mes- 
sage (1-byte body) signifying end-of-file. 
The single byte passed as the body of the 
final short message identifies the system 
disk, and should be passed to the system in 
register AL. 

The entire failure detection, failure recov- 
ery, and slave downloading ""procedure is very 
hardware-dependent. Study the driver listing 
in the appendix for guidance. 
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Comm Driver 



The comm driver supports the TurboDOS commu- 
nications extensions (T-f unctions 34-40) , and 
may be omitted if these functions are not 
used. The driver should be labelled with the 
public entry symbol COMDRV. A comm channel 
number is passed in register CH. The driver 
must perform an I/O operation according to 
the operation code passed in register DLs 



UPL=, 






1 


Return input status in AL 




1 1 


Return input character in AL 




! 2 


Output character passed in CL 




1 3 


Set channel baud rate from CL 




f 4 


Return channel baud rate in AL 




1 5 


Set modem controls from CL 




1 6 


Return modem status in AL 





If DL=0, the driver determines if an input 
character is available. If one is available, 
the driver returns AL=-1, otherwise AL=0. 

If DL=1, the driver returns an input char- 
acter in AL (waiting if necessary). 

If DL=2, the driver outputs the character 
passed in CL. 

If DL=3, the driver sets the channel baud 
rate according to the baud-rate code passed 
in CL. If DL=4, the driver returns the 
channel baud-rate code in AL. See T-func- 
tions 37 and 38 in the MM. ZLQ&L&mmsilZ 
G&1&S for baud-rate code definitions. 

If DL=5, the driver sets the modem controls 
according to the bit-vector passed in CL. If 
DL=6, the driver returns the modem status 
vector in AL. See T-functions 39 and 40 in 
the MM. PX£>9I&mm£JLL& G&1M for bit-vector 
definitions. 



5-13 



TurboDOS 1.4 8086 
Implement or ■ s Guide 



DRIVER INTERFACE 
Clock Driver 



Copyright 1984 by Software 2000, Inc. 
All rights reserved. 



Clock Driver 



The real-time clock driver does not take the 
form of a subroutine called by TurboDOS, as 
do the other drivers described in this sec- 
tion. Rather, the clock driver generally 
consists of an interrupt service routine 
which responds to interrupts from a periodic 
interrupt source (preferably 50 to 60 times a 
second). The interrupt service routine 
should call DLYTIC# once per system tick (to 
synchronize DELAY* requests). It should also 
call RTCSEC* once per second (that is, every 
50 to 60 ticks) to update the system time and 
date. Finally, it should exit by jumping to 
ISRXIT* to provide a periodic dispatcher 
time-slice. Excluding initialization code, a 
typical clock driver might be coded thus: 



1 RTCCNT: 


BYTE 


60 | 


•divide-by-60 cntr 


1 RTCISR: 


PUSH 


AX 


rsave registers 




PUSH 


BX 


n ■ 




PUSH 


CX 


, n n 




PUSH 


DX 


, n n 




PUSH 


DS 


, it n 




CALL 


GETSDS* t 


?get system DS 




CALL 


DLYTIC# , 


f signal one tick 




DEC 


RTCCNT , 


r decrement counter 




JNZ 


_x , 


?not 60 ticks yet 




MOV 


RTCCNT, =6 ( 


) ; reset counter 




CALL 


RTCSEC# t 


', signal one second 


1 X: 


MOV 


DX,&EOIR , 


?DX=&end-of-int 




MOV 


AX,=INTN , 


?AX=interrupt# 




OUT 


DX,AX , 


? reset interrupt 




POP 


DS | 


•restore registers 




POP 


DX t 


, n it 




POP 


CX 


, n it 




POP 


BX , 


, n n 




POP 


AX 


, n it 




JMP 


ISRXIT* 


?go to dispatcher 
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Clock Driver If the hardware is capable of determining the 

of a battery-powered clock, for example), the 
clock driver may initialize the following 
public symbols in the RTCMGR module: 



1 SECS:: 


BYTE 





1 MINS:: 


BYTE 





1 HOURS : : 


BYTE 





1 JDATE : : 


WORD 


0x8001 



/seconds 0-59 
;minutes 0-59 
;hours 0-24 
; Julian date 
;base 31-Dec-47 



5-15 



TurboDOS 1.4 8086 DRIVER INTERFACE 

Implementor ■ s Guide 

Bootstrap 



Copyright 1984 by Software 2000, Inc. 
All rights reserved. 



Bootstrap The bootstrap is usually contained in a ROM 

or on a boot track. Its function is to 
search all disk drives for the TurboDOS 
loader program OSLOAD.CMD, and to load and 
execute it if found. To generate a boot- 
strap, use TLINK to combine the standard 
bootstrap module OSBOOT.O with your own 
hardware-dependent driver. Your driver must 
define the following public names: INIT, 
SELECT, READ, XFER, CODE, and DATA. 

INIT:: is called once to perform any required 
hardware initialization. It returns with 
register AX set to the paragraph address of 
the load base (where the file OSLOAD.CMD 
should be loaded into memory by the boot- 
strap). This address should be chosen so 
that OSLOAD will not overlay the bootstrap or 
the operating system to be loaded. 

SELECT:: is called to select the disk drive 
passed in AL (0-15). If the selected drive 
is not ready or non-existent, it returns 
AL=0. Otherwise, it returns AL=-1 and the 
address of an 11-byte disk specification 
table (DST) in register SI (see page 5-7). 

READ:: is called to read one physical sector 
from the last-selected drive. The track is 
passed in CX, the sector in DX, the DMA 
offset in BX, and the DMA base in ES. It 
must return AL=0 if successful, or AL=-1 if 
an unrecoverable error occurred. 

XFER:: is transferred to at the end of the 
bootstrap process. In most cases, this 
routine must set register DS to the base 
paragraph address of the loader (normally the 
load base returned by INIT:: plus 8 to allow 
for the .CMD header), set location DS:0080 to 
zero (to simulate a null command tail), and 
jump to the loader (using a JMPF to set CS=DS 
and IP=0xl00) . 
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Bootstrap CODE:: defines the base paragraph (CS value) 

(Continued) under which the bootstrap itself is to be 

executed. OSBOOT loads this value into 
register CS before calling INIT::, SELECT::, 
READ:: or XFER::. 

DATA:: defines the base paragraph (DS value) 
of a 128-byte RAM area that OSBOOT may use 
for working storage. (It should not be 
located where OSLOAD.CMD will be loaded!) 
OSBOOT loads this value into register DS 
before calling INIT::, SELECT::, READ:: or 
XFER::. 
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(Intentionally left blank.) 
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OTOASM Command 



Some TurboDOS implementations require that a 
Z80 master processor download 8086-f amily 
slave processors. In writing the network 
circuit driver for the Z80 master processor, 
it is often necessary to embed a download 
bootstrap routine written in 8086 code. The 
utility program OTOASM.CMD is designed to 
simplify this process. 

OTOASM converts an 8086 object file (type .0) 
produced by TASM into a Z80 source file (type 
.ASM) acceptable to either the PASM or M80 
assemblers. The output file contains a 
sequence of data definition statements (.BYTE 
and .WORD, or DB and DW) representing 8086 
machine-language. 



Syntax 



I OTOASM filename {-M} 



Explanation 



The "filename" argument must not have an 
explicit type, and specifies the name of both 
the input file "filename. 0" and the output 
file "filename. ASM" to be used. The "-M" 
option causes the output to be formatted for 
the M80 assembler rather than the PASM assem- 
bler. 

The input file (type .0) must not contain any 
relocatable tokens. Consequently, the 8086 
source module (type .A) must define only 
absolute location counter values (LOC) and 
must make no external references (# suffix). 
Public symbols may be defined as long as they 
do not have relocatable values. 
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SAMPLE DRIVER 
SOURCE LISTINGS 



The remainder of this document consists of 
assembler source listings of actual drivers. 
The listings comprise the drivers for a 
working TurboDOS system for the IBM Personal 
Computer with 256K of RAM. 

The listings appear in the following order: 



L 



_ Module, J, 








DREQUATE 


common 


symbolic equates I 


MPBIPC 


IBM 


PC 


bootstrap driver 1 


NITIPC 


IBM 


PC 


driver initialization 1 


CON I PC 


IBM 


PC 


TTY-mode console driver 1 


LSTPPA 


IBM 


PC 


parallel printer driver 1 


LSTACA 


IBM 


PC 


serial printer driver 1 


RTCIPC 


IBM 


PC 


real-time clock driver 1 


DSKIPC 


IBM 


PC 


floppy disk driver 1 


1 MSTIPC 


IBM 


PC 


memory spec table (256K) 1 



Network circuit drivers will be furnished in 
the next edition of this document. In the 
meantime, refer to the 1M IflLBJLejBJ 
GJ&1&& for circuit driver examples. 
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Note: Sample source listings are available upon request. 
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